OS/2 Shareware BBS: 10 Tools

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / netpbma.zip / vms / PBMplus.hlp < prev next >

Wrap

Text File | 1994-02-28 | 234KB | 6,815 lines

1 HELP See PBMplus and OVERVIEW. 1 OVERVIEW Enhanced portable bitmap toolkit. 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**2 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: pbm Supports monochrome bitmaps (1 bit per pixel). pgm Supports grayscale images. Reads either PBM or PGM formats and writes PGM format. ppm Supports full-color images. Reads either PBM, PGM, or PPM formats, writes PPM format. pnm Supports content-independent manipulations on any of the three formats listed above, as well as external formats having multiple types. Reads either PBM, PGM, or PPM formats, and generally writes the same type as it read (whenever a PNM tool makes an exception and ``promotes'' a file to a higher format, it informs the user). See PBMplus for more infomation. 1 PBMplus Enhanced portable bitmap toolkit. 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**2 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: pbm Supports monochrome bitmaps (1 bit per pixel). pgm Supports grayscale images. Reads either PBM or PGM formats and writes PGM format. ppm Supports full-color images. Reads either PBM, PGM, or PPM formats, writes PPM format. pnm Supports content-independent manipulations on any of the three formats listed above, as well as external formats having multiple types. Reads either PBM, PGM, or PPM formats, and generally writes the same type as it read (whenever a PNM tool makes an exception and ``promotes'' a file to a higher format, it informs the user). 2 Description_of_Contents A brief, one-line description of each of the individual programs in the PBMplus package. They are sorted by general type. 3 pbm atktopbm convert Andrew Toolkit raster object to portable bitmap brushtopbm convert Xerox doodle brushes to portable bitmap cmuwmtopbm convert CMU window manager format to portable bitmap g3topbm convert Group 3 FAX to portable bitmap icontopbm convert Sun icon to portable bitmap gemtopbm convert GEM .img format to portable bitmap macptopbm convert MacPaint to portable bitmap mgrtopbm convert MGR format to portable bitmap pktopbm convert packed (PK) format font into portable bitmap(s) pbmmerge merge wrapper routine pbmto10x convert portable bitmap to Gemini 10x printer graphics pbmto4425 convert portable bitmap to AT&T 4425 terminal pbmtoascii convert portable bitmap to ASCII graphic form pbmtoatk convert portable bitmap to Andrew Toolkit raster object pbmtobbnbg convert portable bitmap to BBN BitGraph graphics pbmtocmuwm convert portable bitmap to CMU window manager format pbmtoepson convert portable bitmap to Epson printer graphics pbmtog3 convert portable bitmap to Group 3 FAX pbmtogem convert portable bitmap into GEM .img file pbmtogo convert portable bitmap to GraphOn graphics pbmtoicon convert portable bitmap to Sun icon pbmtolj convert portable bitmap to HP LaserJet graphics pbmtoln03 convert portable bitmap to DEC LN03+ Laserprinter pbmtolps convert portable bitmap to PostScript pbmtomacp convert portable bitmap to MacPaint pbmtomgr convert portable bitmap to MGR format pbmtopgm convert portable bitmap to portable graymap by ave. areas pbmtopi3 convert portable bitmap to Atari Degas .pi3 pbmtopk convert portable bitmap into a packed (PK) format font pbmtoplot convert portable bitmap into Unix plot(5) file pbmtoptx convert portable bitmap to Printronix graphics pbmtoxbm convert portable bitmap to X11 bitmap pbmtox10bm convert portable bitmap to X10 bitmap pbmtoybm convert portable bitmap into Bennet Yee "face" file pbmtozinc convert portable bitmap to Zinc Interface Library icon pbmtoepsi convert portable bitmap into an encapsulated PostScript pi3topbm convert Atari Degas .pi3 to portable bitmap xbmtopbm convert X10 or X11 bitmap to portable bitmap ybmtopbm convert Bennet Yee "face" file into portable bitmap pbmclean flip isolated pixels in portable bitmap pbmlife apply Conway's rules of Life to a portable bitmap pbmmake create a blank bitmap of a specified size and color pbmmask create a mask bitmap from a regular bitmap pbmreduce reduce a portable bitmap N times, using Floyd-Steinberg pbmspcale enlarge a portable bitmap with edge smoothing pbmtext render text into a bitmap pbmupc create a Universal Product Code bitmap 3 pgm asciitopgm convert ASCII graphics into a portable graymap fstopgm convert Usenix FaceSaver format to portable graymap hipstopgm convert HIPS format to portable graymap lispmtopgm convert a Lisp Machine bitmap file into pgm format bioradtopgm convert a Biorad confocal file into a portable graymap psidtopgm convert PostScript "image" data to portable graymap rawtopgm convert raw grayscale bytes to portable graymap spottopgm convert SPOT satellite images to Portable Greymap format pgmtofs convert portable graymap to Usenix FaceSaver format pgmtolispm convert a portable graymap into Lisp Machine format pgmtopbm convert portable graymap to portable bitmap pgmbentley Bentleyize a portable graymap pgmcrater create cratered terrain by fractal forgery pgmedge edge-detect a portable graymap pgmenhance edge-enhance a portable graymap pgmhist print a histogram of the values in a portable graymap pgmkernel generate a convolution kernel pgmmerge merge wrapper routine pgmnoise create a graymap made up of white noise pgmnorm normalize contrast in a portable graymap pgmoil turn a portable graymap into an oil painting pgmramp generate a grayscale ramp pgmtexture calculate textural features on a portable graymap 3 ppm bmptoppm convert BMP file to portable pixmap gouldtoppm convert Gould scanner file to portable pixmap ilbmtoppm convert IFF ILBM to portable pixmap imgtoppm convert Img-whatnot to portable pixmap mtvtoppm convert MTV ray-tracer output to portable pixmap pcxtoppm convert PC Paintbrush format to portable pixmap pgmtoppm colorize a portable graymap into a portable pixmap pi1toppm convert Atari Degas .pi1 to portable pixmap picttoppm convert Macintosh PICT to portable pixmap pjtoppm convert HP PaintJet file to portable pixmap ppmtoacad convert portable pixmap to AutoCAD database or slide ppmtobmp convert portable pixmap to BMP file ppmtogif convert portable pixmap to GIF ppmtoicr convert portable pixmap to NCSA ICR graphics ppmtoilbm convert portable pixmap to IFF ILBM ppmtomitsu convert a portable pixmap to a Mitsubishi S340-10 file ppmtomap extract all colors from a portable pixmap ppmtopcx convert portable pixmap to PC Paintbrush format ppmtopgm convert portable pixmap to portable graymap ppmtopi1 convert portable pixmap to Atari Degas .pi1 ppmtopict convert portable pixmap to Macintosh PICT ppmtopj convert portable pixmap to HP PaintJet file ppmtopjxl convert portable pixmap to HP PaintJet XL PCL file ppmtopuzz convert portable pixmap to X11 "puzzle" file ppmtorgb3 separate a portable pixmap to three portable graymaps ppmtosixel convert portable pixmap to DEC sixel format ppmtotga convert portable pixmap to TrueVision Targa file ppmtouil convert portable pixmap to Motif UIL icon file ppmtoxpm convert portable pixmap to XPM format ppmtoyuv convert portable pixmap to Abekas YUV format qrttoppm convert QRT ray-tracer output to portable pixmap rawtoppm convert raw RGB bytes to portable pixmap rgb3toppm combine three portable graymaps to one portable pixmap sldtoppm convert an AutoCAD slide file into a portable pixmap spctoppm convert Atari compressed Spectrum to portable pixmap sputoppm convert Atari uncompressed Spectrum to portable pixmap tgatoppm convert TrueVision Targa file to portable pixmap ximtoppm convert Xim to portable pixmap xpmtoppm convert XPM format to portable pixmap xvminitoppm convert a XV "thumbnail" picture to PPM yuvtoppm convert Abekas YUV format to portable pixmap ppm3d convert 2 portable pixmap to a red/blue 3d glasses pixmap ppmbrighten change images Saturation and Value from an HSV map ppmchange change pixels of one color to another in a portable pixmap ppmdim dim a portable pixmap down to total blackness ppmdist simple grayscale for machine generated, color images ppmdither ordered dither for color images ppmflash brighten a picture up to complete white-out ppmforge fractal forgeries of clouds, planets, and starry skies ppmhist print a histogram of a portable pixmap ppmmake create a pixmap of a specified size and color ppmmix blend together two portable pixmaps ppmpat create a pretty pixmap ppmquant quantize colors down to a specified number ppmqvga 8 plane quantization ppmrelief run a Laplacian Relief filter on a portable pixmap ppmshift shift lines of a portable pixmap left or right by a random amount ppmspread displace a portable pixmap's pixels by a random amount 3 pnm pnmtoddif convert portable anymap to DDIF format pnmtofits convert a portable anymap into FITS format pnmtops convert portable anymap to PostScript pnmtorast convert portable anymap to Sun raster file pnmtotiff convert portable anymap to TIFF file pnmtoxwd convert portable anymap to X11 window dump fitstopnm convert a FITS file into a portable anymap rasttopnm convert Sun raster file to portable anymap tifftopnm convert TIFF file to portable anymap xwdtopnm convert X10 or X11 window dump to portable anymap pnmtosir convert a portable anymap into a Solitaire format sirtopnm convert a Solitaire file into a portable anymap zeisstopnm convert a Zeiss confocal file into a portable anymap pnmalias antialias a portable anyumap. pnmarith perform arithmetic on two portable anymaps pnmcat concatenate portable anymaps pnmcomp composite two portable anymap files together pnmconvol general MxN convolution on a portable anymap pnmcrop crop all like-colored borders off a portable anymap pnmcut select a rectangular region from a portable anymap pnmdepth change the maxval in a portable anymap pnmenlarge enlarge a portable anymap N times pnmfile describe a portable anymap pnmflip perform one or more flip operations on a portable anymap pnmgamma perform gamma correction on a portable anymap pnmhistmap draw a histogram for a PGM or PPM file pnminvert invert a portable anymap pnmnlfilt non-linear filters: smooth, alpha trim mean, optimal estimation smoothing, edge enhancement pnmnoraw force a portable anymap into ASCII format pnmpad add borders to portable anymap pnmpaste paste a rectangle into a portable anymap pnmrotate rotate a portable anymap pnmscale scale a portable anymap pnmshear shear a portable anymap pnmtile replicate a portable anymap into a specified size 2 See_Also There are a number of related image-manipulation tools: IM Raster Toolkit A portable and efficient format toolkit. The format supports pixels of arbitrary channels, components, and bit precisions, while allowing compression and machine byte-order independence. Support for image manipulation, digital halftoning, and format conversion. Previously distributed on tape c/o the University of Waterloo (an ftp version is to appear later). Author: Alan Paeth (awpaeth@watcgl.uwaterloo.ca). Utah RLE Toolkit Conversion and manipulation package, similar to PBMPLUS. Available via ftp as cs.utah.edu: pub/toolkit-2.0.tar.Z and ucsd.edu: graphics/utah-raster-toolkit.tar.Z. Fuzzy Pixmap Manipulation Conversion and manipulation package, similar to PBMPLUS. Version 1.0 available via ftp as nl.cs.cmu.edu: /usr/mlm/ftp/fbm.tar.Z, uunet.uu.net: pub/fbm.tar.Z, and ucsd.edu: graphics/fbm.tar.Z. Author: Michael Mauldin (mlm@nl.cs.cmu.edu). Img Software Set Reads and writes its own image format, displaying results on an X11 screen, and does some image manipulations. Version 1.3 is available via ftp as ftp.x.org:contrib/img_1.3.tar.Z, and venera.isi.edu:pub/img_1.3.tar.Z, along with a large collection of color images. Author: Paul Raveling (raveling@venera.isi.edu). Xim Reads and writes its own image format, displays on an X11 screen, and does some image manipulations. Available in your nearest X11R4 source tree as it contrib/clients/xim. A more recent version is available via ftp from video.mit.edu. It uses X11R4 and the OSF/Motif toolkit to provide basic interactive image manipulation and reads/writes GIF, xwd, xbm, tiff, rle, xim, and other formats. Author: Philip R. Thompson. xloadimage Reads in images in various formats and displays them on an X11 screen. Available via ftp as ftp.x.org:contrib/xloadimage*, and in your nearest comp.sources.x archive. Author: Jim Frost (madd@std.com). TIFF Software Nice portable library for reading and writing TIFF files, plus a few tools for manipulating them and reading other formats. Available via ftp as sgi.com:pub/graphics/*.tar.Z or uunet.uu.net:graphics/tiff.tar.Z. Author: Sam Leffler (sam@sgi.com). ALV A Sun-specific image toolkit. Version 2.0.6 posted to comp.sources.sun on 11 December 1989. Also available via email to alv-users-request@cs.bris.ac.uk. popi An image manipulation language. Version 2.1 posted to comp.sources.misc on 12 December 1989. ImageMagick X11 package for display and interactive manipulation of images. Uses its own format (MIFF), and includes some converters. Available via ftp as ftp.x.org:contrib/ImageMagick.tar.Z. Khoros Huge (~100 meg) graphical development environment based on X11R4. Components include a visual programming language, code generators for extending the visual language and adding new application packages to the system, an interactive user interface editor, an interactive image display package, an extensive library of image and signal processing routines, and 2D/3D plotting packages. Available via ftp as pprg.unm.edu:pub/khoros/*. JPEG package JPEG is a a standardized compression method for full-color and gray-scale images of "real-world" scenes; this experimental package includes programs to compress gif and ppm format files to JPEG format ( cjpeg(1L)), and to decompress them (djpeg(1L)). Available by ftp as uunet.uu.net:graphics/jpeg/jpegsrc.v1.tar.Z. libpbm(3L), libpgm(3L), libpnm(3L), libppm(3L), pbm(5L), pgm(5L), pnm(5L), ppm(5L), rasterfile(1) 2 Author Distribution of 1 December 1991. Copyright 1989, 1991 by Jef Poskanzer. Feedback and questions are welcome. Please send them to: jef@well.sf.ca.us apple!well!jef 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. 1 asciitopgm asciitopgm - convert ASCII graphics into a portable graymap 2 Synopis asciitopgm [-d divisor] height width [asciifile] 2 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." 2 Bugs The table of ASCII-to-grey values is subject to interpretation, and, of course, depends on the typeface intended for the input. 2 See_Also pbmtoascii(1), pgm(5) 2 Author Wilson H. Bent. Jr. (whb@usc.edu) 1 atktopbm atktopbm - convert Andrew Toolkit raster object to portable bitmap 2 Synopsis atktopbm [atkfile] 2 Description Reads an Andrew Toolkit raster object as input. Produces a portable bitmap as output. 2 See_Also pbmtoatk, pbm 2 Author Copyright (C) 1991 by Bill Janssen. 1 brushtopbm brushtopbm - convert a doodle brush file into a portable bitmap 2 Synopsis brushtopbm [brushfile] 2 Description Reads a Xerox doodle brush file as input. Produces a port- able bitmap as output. Note that there is currently no pbmtobrush tool. 2 See_Also pbm 2 Author Copyright (C) 1988 by Jef Poskanzer. 1 cmuwmtopbm cmuwmtopbm - convert a CMU window manager bitmap into a portable bitmap 2 Synopsis cmuwmtopbm [cmuwmfile] 2 Description Reads a CMU window manager bitmap as input. Produces a portable bitmap as output. 2 See_Also pbmtocmuwm, pbm 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 g3topbm g3topbm - convert a Group 3 fax file into a portable bitmap 2 Synopsis g3topbm [-kludge] [-reversebits] [-stretch] [g3file] 2 Description Reads a Group 3 fax file as input. Produces a portable bit- map as output. 2 Options -kludge Tells g3topbm to ignore the first few lines of the file; sometimes fax files have some junk at the begin- ning. -reversebits Tells g3topbm to interpret bits least-significant first, instead of the default most-significant first. Apparently some fax modems do it one way and others do it the other way. If you get a whole bunch of "bad code word" messages, try using this flag. -stretch Tells g3topbm to stretch the image vertically by dupli- cating each row. This is for the low-quality transmis- sion mode. All flags can be abbreviated to their shortest unique pre- fix. 2 References The standard for Group 3 fax is defined in CCITT Recommenda- tion T.4. 2 Bugs Probably. 2 See_Also pbmtog3, pbm 2 Author Copyright (C) 1989 by Paul Haeberli <paul@manray.sgi.com>. 1 icontopbm icontopbm - convert a Sun icon into a portable bitmap 2 Synopsis icontopbm [iconfile] 2 Description Reads a Sun icon as input. Produces a portable bitmap as output. 2 See_Also pbmtoicon, pbm 2 Author Copyright (C) 1988 by Jef Poskanzer. 1 gemtopbm gemtopbm - convert a GEM .img file into a portable bitmap 2 Synopsis gemtopbm [-d] gemfile 2 Description Reads a GEM .img file as input. Produces a portable bitmap as output. 2 Options -d Produce output describing the contents of the .img file. 2 Bugs Does not support file containing more than one plane. Can't read from standard input. 2 See_Also pbmtogem, pbm 2 Author Copyright (C) 1988 Diomidis D. Spinellis (dds@cc.ic.ac.uk). 1 macptopbm macptopbm - convert a MacPaint file into a portable bitmap 2 Synopsis macptopbm [-extraskip N] [macpfile] 2 Description Reads a MacPaint file as input. Produces a portable bitmap as output. 2 Options -extraskip This flag is to get around a problem with some methods of transferring files from the Mac world to the Unix world. Most of these methods leave the Mac files alone, but a few of them add the "finderinfo" data onto the front of the Unix file. This means an extra 128 bytes to skip over when reading the file. The symptom to watch for is that the resulting PBM file looks shifted to one side. If you get this, try -extraskip 128, and if that still doesn't look right try another value. All flags can be abbreviated to their shortest unique pre- fix. 2 See_Also picttoppm, pbmtomacp, pbm 2 Author Copyright (C) 1988 by Jef Poskanzer. The MacPaint-reading code is copyright (c) 1987 by Patrick J. Naughton (naughton@wind.sun.com). 1 mgrtopbm mgrtopbm - convert a MGR bitmap into a portable bitmap 2 Synopsis mgrtopbm [mgrfile] 2 Description Reads a MGR bitmap as input. Produces a portable bitmap as output. 2 See_Also pbmtomgr, pbm 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 pbmclean pbmclean - flip isolated pixels in portable bitmap 2 Synopsis pbmclean [-connect] [pbmfile] 2 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. 2 See_Also pbm 2 Author Copyright (C) 1990 by Angus Duggan Copyright (C) 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 docu- mentation. This software is provided "as is" without express or implied warranty. 1 pbmlife pbmlife - apply Conway's rules of Life to a portable bitmap 2 Synopsis pbmlife [pbmfile] 2 Description Reads a portable bitmap as input. Applies the rules of Life to it for one generation, and produces a portable bitmap as output. A white pixel in the image is interpreted as a live beastie, and a black pixel as an empty space. 2 See_Also pbm 2 Author Copyright (C) 1988, 1991 by Jef Poskanzer. 1 pbmmake pbmmake - create a blank bitmap of a specified size 2 Synopsis pbmmake [-white|-black|-gray ] width height 2 Description Produces a portable bitmap of the specified width and height. The color defaults to white. 2 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. All flags can be abbreviated to their shortest unique pre- fix. 2 See_Also pbm, ppmmake 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 pbmmask pbmmask - create a mask bitmap from a regular bitmap 2 Synopsis pbmmask [-expand] [pbmfile] 2 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 boun- dary between the two images less sharp. -expand Expands the mask by one pixel out from the image. This is useful if you want a little white border around your image. (A better solution might be to turn the pbmlife tool into a general cellular automaton tool...) 2 See_Also pnmpaste, pnminvert, pbm, pnmarith, pnmsmooth 2 Author Copyright (C) 1988 by Jef Poskanzer. 1 pbmpscale pbmpscale - enlarge a portable bitmap with edge smoothing 2 Synopsis pbmpscale N [ pbmfile ] 2 Description Reads a portable bitmap as input, and outputs a portable bitmap enlarged N times. Enlargement is done by pixel repli- cation, with some additional smoothing of corners and edges. 2 See_Also pnmenlarge, ppmscale, pbm 2 Author Copyright (C) 1990 by Angus Duggan Copyright (C) 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 docu- mentation. This software is provided "as is" without express or implied warranty. 2 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. 1 pbmreduce pbmreduce - read a portable bitmap and reduce it N times 2 Synopsis pbmreduce [-floyd|-fs|-threshold ] [-value val] N [pbmfile] 2 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. 2 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 threshold- ing. This gives better results when reducing line drawings. The -value flag alters the thresholding value for all quant- izations. 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 pre- fix. 2 See_Also pnmenlarge, pnmscale, pgmtopbm, pbm 2 Author Copyright (C) 1988 by Jef Poskanzer. 1 pbmtext pbmtext - render text into a bitmap 2 Synopsis pbmtext [-font fontfile] [text] 2 Description Takes the specified text, either a single line from the com- mand line or multiple lines from standard input, and renders it into a bitmap. 2 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: M ",/^_[`jpqy| M / !"#$%&'()*+ / < ,-./01234567 < > 89:;<=>?@ABC > @ DEFGHIJKLMNO @ _ PQRSTUVWXYZ[ _ { \]^_`abcdefg { } hijklmnopqrs } ~ tuvwxyz{|}~ ~ M ",/^_[`jpqy| M 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 every- thing 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. 2 See_Also pbm, pnmcut, pnmcrop 2 Author Copyright (C) 1991 by Jef Poskanzer. 1 pbmto4425 pbmto4425 - Display PBM images on an AT&T 4425 terminal 2 Synopsis pbmto4425 [pbmfile] 2 Description Pbmto4425 displays PBM format images on an AT&T 4425 ASCII terminal using that terminal's mosaic graphics character set. The program should also work with other VT100-like terminals with mosaic graphics character sets such as the C. Itoh CIT-101, but it has not yet been tested on terminals other than the 4425. Pbmto4425 puts the terminal into 132 column mode to achieve the maximum resolution of the terminal. In this mode the terminal has a resolution of 264 columns by 69 rows. The pixels have an aspect ratio of 1:2.6, therefore an image should be processed before being displayed in a manner such as this: % pnmscale -xscale 2.6 pnmfile \ | pnmscale -xysize 264 69 \ | ppmtopgm \ | pgmtopbm \ | pbmto4425 2 Author Copyright (C) 1993 by Robert Perlberg 1 pbmto10x pbmto10x - convert a portable bitmap into Gemini 10X printer graphics 2 Synopsis pbmto10x [-h] [pbmfile] 2 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. Note that there is no 10xtopbm tool - this transformation is one way. 2 Options The resolution is normally 60H by 72V. If the -h flag is specified, resolution is 120H by 144V. You may find it use- ful to rotate landscape images before printing. 2 See_Also pbm 2 Author Copyright (C) 1990 by Ken Yap 1 pbmtoascii pbmtoascii - convert a portable bitmap into ASCII graphics 2 Synopsis pbmtoascii [-1x2|-2x4] [pbmfile] 2 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. 2 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. 2 See_Also pbm 2 Author Copyright (C) 1988, 1992 by Jef Poskanzer. 1 pbmtoatk pbmtoatk - convert portable bitmap to Andrew Toolkit raster object 2 Synopsis pbmtoatk [pbmfile] 2 Description Reads a portable bitmap as input. Produces a Andrew Toolkit raster object as output. 2 See_Also atktopbm, pbm 2 Author Copyright (C) 1991 by Bill Janssen. 1 pbmtobg pbmtobg - convert a portable bitmap into BitGraph graphics 2 Synopsis pbmtobg [rasterop] [x y] < pbmfile 2 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. Note that there is no bgtopbm tool. 2 See_Also pbm 2 Author Copyright 1989 by Mike Parker. 1 pbmtocmuwm pbmtocmuwm - convert a portable bitmap into a CMU window manager bitmap 2 Synopsis pbmtocmuwm [pbmfile] 2 Description Reads a portable bitmap as input. Produces a CMU window manager bitmap as output. 2 See_Also cmuwmtopbm, pbm 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 pbmtoepsi pbmtoepsi - convert a portable bitmap into an encapsulated PostScript style preview bitmap 2 Synopsis pbmtoepsi [-bbonly] [pbmfile] 2 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). 2 Options -bbonly Only create a boundary box, don't fill it with the image. 2 See_Also pbm, pnmtops, psidtopgm 2 Author Copyright (C) 1988 Jef Poskanzer, modified by Doug Crabill 1992 1 pbmtoepson pbmtoepson - convert a portable bitmap into Epson printer graphics 2 Synopsis pbmtoepson [pbmfile] 2 Description Reads a portable bitmap as input. Produces a file of Epson printer graphics as output. Note that there is no epsontopbm tool - this transformation is one way. 2 See_Also pbm 2 Author Copyright (C) 1991 by John Tiller (tiller@galois.msfc.nasa.gov) and Jef Poskanzer. 1 pbmtog3 pbmtog3 - convert a portable bitmap into a Group 3 fax file 2 Synopsis pbmtog3 [pbmfile] 2 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 Recommenda- tion T.4. 2 Bugs Probably. 2 See_Also g3topbm, pbm 2 Author Copyright (C) 1989 by Paul Haeberli <paul@manray.sgi.com>. 1 pbmtogem pbmtogem - convert a portable bitmap into a GEM .img file 2 Synopsis pbmtogem [pbmfile] 2 Description Reads a portable bitmap as input. Produces a GEM .img file as output. 2 Bugs It does not support compression of the data. 2 See_Also gemtopbm, pbm 2 Author Copyright (C) 1988 by David Beckemeyer (bdt!david) and Jef Poskanzer. 1 pbmtogo pbmtogo - convert a portable bitmap into compressed GraphOn graphics 2 Synopsis pbmtogo [pbmfile] 2 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. 2 See_Also pbm 2 Author Copyright (C) 1988, 1989 by Jef Poskanzer, Michael Haberler, and Bo Thide'. 1 pbmtoicon pbmtoicon - convert a portable bitmap into a Sun icon 2 Synopsis pbmtoicon [pbmfile] 2 Description Reads a portable bitmap as input. Produces a Sun icon as output. 2 See_Also icontopbm, pbm 2 Author Copyright (C) 1988 by Jef Poskanzer. 1 pbmtolj pbmtolj - convert a portable bitmap into HP LaserJet format 2 Synopsis pbmtolj [-resolution N] [pbmfile] 2 Description Reads a portable bitmap as input. Produces HP LaserJet data as output. Note that there is no ljtopbm tool. 2 Options -resolution Specifies the resolution of the output device, in dpi. Typical values are 75, 100, 150, 300. The default is 75. All flags can be abbreviated to their shortest unique pre- fix. 2 See_Also pbm 2 Author Copyright (C) 1988 by Jef Poskanzer and Michael Haberler. 1 pbmtoln03 pbmtoln03 - convert protable bitmap to DEC LN03+ Sixel out- put 2 Synopsis pbmtoln03 [-rltbf] pbmfile 2 Description Reads a portable bitmap as input. Produces a DEC LN03+ Sixel output file. 2 Options -l nn Use "nn" as value for left margin (default 0). -r nn Use "nn" as value for right margin (default 2400). -t nn Use "nn" as value for top margin (default 0). -b nn Use "nn" as value for bottom margin (default 3400). -f nn Use "nn" as value for form length (default 3400). 2 See_Also pbm 2 Author Tim Cook, 26 Feb 1992 1 pbmtolps pbmtolps - convert portable bitmap to PostScript 2 Synopsis pbmtolps [ -dpi n ] [ pbmfile ] 2 Description Reads a portable bitmap as input, and outputs PostScript. The output Postscript uses lines instead of the image opera- tor 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. 2 See_Also pgmtops, ppmtops, pbm 2 Author George Phillips <phillips@cs.ubc.ca> 1 pbmtomacp pbmtomacp - convert a portable bitmap into a MacPaint file 2 Synopsis pbmtomacp [-l left] [-r right] [-b bottom] [-t top] [pbmfile] 2 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. 2 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 ). 2 Bugs The source code contains comments in a language other than English. 2 See_Also ppmtopict, macptopbm, pbm, mcvert 2 Author Copyright (C) 1988 by Douwe van der Schaaf (...!mcvax!uvapsy!vdschaaf). 1 pbmtomgr pbmtomgr - convert a portable bitmap into a MGR bitmap 2 Synopsis pbmtomgr [pbmfile] 2 Description Reads a portable bitmap as input. Produces a MGR bitmap as output. 2 See_Also mgrtopbm, pbm 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 pbmtopi3 pbmtopi3 - convert a portable bitmap into an Atari Degas .pi3 file 2 Synopsis pbmtopi3 [pbmfile] 2 Description Reads a portable bitmap as input. Produces an Atari Degas .pi3 file as output. 2 See_Also pi3topbm, pbm, ppmtopi1, pi1toppm 2 Author Copyright (C) 1988 by David Beckemeyer (bdt!david) and Jef Poskanzer. 1 pbmtoplot pbmtoplot - convert a portable bitmap into a Unix plot file 2 Synopsis pbmtoplot [pbmfile] 2 Description Reads a portable bitmap as input. Produces a Unix plot file. Note that there is no plottopbm tool - this transformation is one-way. 2 See_Also pbm, plot 2 Author Copyright (C) 1990 by Arthur David Olson. 1 pbmtoptx pbmtoptx - convert a portable bitmap into Printronix printer graphics 2 Synopsis pbmtoptx [pbmfile] 2 Description Reads a portable bitmap as input. Produces a file of Prin- tronix printer graphics as output. Note that there is no ptxtopbm tool - this transformation is one way. 2 See_Also pbm 2 Author Copyright (C) 1988 by Jef Poskanzer. 1 pbmtox10bm pbmtox10bm - convert a portable bitmap into an X10 bitmap 2 Synopsis pbmtox10bm [pbmfile] 2 Description Reads a portable bitmap as input. Produces an X10 bitmap as output. This older format is maintained for compatibility. Note that there is no x10bmtopbm tool, because xbmtopbm can read both X11 and X10 bitmaps. 2 See_Also pbmtoxbm, xbmtopbm, pbm 2 Author Copyright (C) 1988 by Jef Poskanzer. 1 pbmtoxbm pbmtoxbm - convert a portable bitmap into an X11 bitmap 2 Synopsis pbmtoxbm [pbmfile] 2 Description Reads a portable bitmap as input. Produces an X11 bitmap as output. 2 See_Also pbmtox10bm, xbmtopbm, pbm 2 Author Copyright (C) 1988 by Jef Poskanzer. 1 pbmtoybm pgmtoybm - convert a portable bitmap into a Bennet Yee "face" file 2 Synopsis pbmtoybm [pbmfile] 2 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). 2 See_Also ybmtopbm, pbm, face, face, xbm 2 Author Copyright (C) 1991 by Jamie Zawinski and Jef Poskanzer. 1 pbmtozinc pbmtozinc - convert a portable bitmap into a Zinc bitmap 2 Synopsis pbmtozinc [pbmfile] 2 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. 2 See_Also pbm 2 Author Copyright (C) 1988 by James Darrell McCauley (jdm5548@diamond.tamu.edu) and Jef Poskanzer. 1 pbmupc pbmupc - create a Universal Product Code bitmap 2 Synopsis pbmupc [-s1|-s2] type manufac product 2 Description Generates a Universal Product Code symbol. The three argu- ments are: a one digit product type, a five digit manufac- turer 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. 2 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|| 2 See_Also pbm 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 pi3topbm pi3topbm - convert an Atari Degas .pi3 file into a portable bitmap 2 Synopsis pi3topbm [pi3file] 2 Description Reads an Atari Degas .pi3 file as input. Produces a port- able bitmap as output. 2 See_Also pbmtopi3, pbm, pi1toppm, ppmtopi1 2 Author Copyright (C) 1988 by David Beckemeyer (bdt!david) and Diomidis D. Spinellis. 1 pktopbm pktopbm - convert packed (PK) format font into portable bitmap(s) 2 Synopsis pktopbm pkfile[.pk] [-c num] pbmfile ... 2 Description Reads a packed (PK) font file as input, and produces port- able 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. 2 Options -c num Sets the character number of the next bitmap written to num. 2 See_Also pbmtopk, pbm 2 Author Adapted from Tom Rokicki's pxtopk by Angus Duggan <ajcd@uk.ac.ed.lfcs>. 1 xbmtopbm xbmtopbm - convert an X11 or X10 bitmap into a portable bit- map 2 Synopsis xbmtopbm [bitmapfile] 2 Description Reads an X11 or X10 bitmap as input. Produces a portable bitmap as output. 2 See_Also pbmtoxbm, pbmtox10bm, pbm 2 Author Copyright (C) 1988 by Jef Poskanzer. 1 ybmtopbm ybmtopbm - convert a Bennet Yee "face" file into a portable bitmap 2 Synopsis ybmtopbm [facefile] 2 Description Reads a file acceptable to the face and xbm programs by Ben- net Yee (bsy+@cs.cmu.edu). Writes a portable bitmap as out- put. 2 See_Also pbmtoybm, pbm, face, face, xbm 2 Author Copyright (C) 1991 by Jamie Zawinski and Jef Poskanzer. 1 pbmtopk pbmtopk - convert a portable bitmap into a packed (PK) for- mat font 2 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]... 2 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. 2 Options -s designsize Sets the design size of the font, in TeX's points (72.27pt to the inch). The default design size is 1. The TFM parameters are given as multiples of the design size. -p num param... Sets the first num font parameters for the font. The first seven parameters are the slant, interword spac- ing, interword space stretchability, interword space shrinkability, x-height, quad width, and post-sentence extra space of the font. Math and symbol fonts may have more parameters; see The TeXbook for a list of these. Reasonable default values are chosen for parameters which are not specified. -C codingscheme Sets the coding scheme comment in the TFM file. -F family Sets the font family comment in the TFM file. -f optfile Reads the file optfile, which should contain a lines of the form: filename xoff yoff horiz vert width height depth ital The pbm files specified by the filename parameters are inserted consecutively in the font with the specified attributes. If any of the attributes are omitted, or replaced with "*", a default value will be calculated from the size of the bitmap. The settings of the -W, -H, -D, -I, -h, -v, -x, and -y options do not affected characters created in this way. The character number can be changed by including a line starting with "=", followed by the new number. Lines beginning with "%" or "#" are ignored. -c num Sets the character number of the next bitmap encoun- tered to num. -W width Sets the TFM width of the next character to width (in design size multiples). -H height Sets the TFM height of the next character to height (in design size multiples). -D depth Sets the TFM depth of the next character to depth (in design size multiples). -I ital Sets the italic correction of the next character to ital (in design size multiples). -h horiz Sets the horizontal escapement of the next character to horiz (in pixels). -v vert Sets the vertical escapement of the next character to vert (in pixels). -x xoff Sets the horizontal offset of the next character to xoff (in pixels). -y yoff Sets the vertical offset of the next character to yoff (in pixels, from the top row). 2 See_Also pktopbm, pbm 2 Author Adapted from Tom Rokicki's pxtopk by Angus Duggan <ajcd@uk.ac.ed.lfcs>. 1 libpbm C LIBRARY FUNCTIONS libpbm libpbm - functions to support portable bitmap programs 2 Synopsis #include <pbm.h> cc ... libpbm.a 2 Description - PACKAGE-WIDE ROUTINES KEYWORD MATCHING int pm_keymatch( char* str, char* keyword, int minchars ) Does a case-insensitive match of str against keyword. str can be a leading sunstring of keyword, but at least minchars must be present. LOG BASE TWO int pm_maxvaltobits( int maxval ) int pm_bitstomaxval( int bits ) Convert between a maxval and the minimum number of bits required to hold it. MESSAGES AND ERRORS void pm_message( char* fmt, ... ) printf() style routine to write an informational message. void pm_error( char* fmt, ... ) printf() style routine to write an error message and abort. void pm_usage( char* usage ) Write a usage message. The string should indicate what arguments are to be provided to the program. GENERIC FILE MANAGEMENT FILE* pm_openr( char* name ) Open the given file for reading, with appropriate error checking. A filename of "-" is taken as equivalent to stdin. FILE* pm_openw( char* name ) Open the given file for writing, with appropriate error checking. void pm_close( FILE* fp ) Close the file descriptor, with appropriate error checking. ENDIAN I/O 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. 2 Description - PBM-SPECIFIC ROUTINES TYPES AND CONSTANTS typedef ... bit; #define PBM_WHITE ... #define PBM_BLACK ... each bit should contain only the values of PBM_WHITE or PBM_BLACK. #define PBM_FORMAT ... #define RPBM_FORMAT ... #define PBM_TYPE PBM_FORMAT #define PBM_FORMAT_TYPE(f) ... For distinguishing different file formats and types. INITIALIZATION void pbm_init( int* argcP, char* argv[] ) All PBM programs must call this routine. MEMORY MANAGEMENT bit** pbm_allocarray( int cols, int rows ) Allocate an array of bits. bit* pbm_allocrow( int cols ) Allocate a row of the given number of bits. void pbm_freearray( bit** bits, int rows ) Free the array allocated with pbm_allocarray() containing the given number of rows. void pbm_freerow( bit* bitrow ) Free a row of bits. READING FILES void pbm_readpbminit( FILE* fp, int* colsP, int* rowsP, int* formatP ) Read the header from a PBM file, filling in the rows, cols and format variables. void pbm_readpbmrow( FILE* fp, bit* bitrow, int cols, int format ) Read a row of bits into the bitrow array. Format and cols were filled in by pbm_readpbminit(). bit** pbm_readpbm( FILE* fp, int* colsP, int* rowsP ) Read an entire bitmap file into memory, returning the allo- cated array and filling in the rows and cols variables. This function combines pbm_readpbminit(), pbm_allocarray() and pbm_readpbmrow(). char* pm_read_unknown_size( FILE* fp, long* nread ) 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. WRITING FILES void pbm_writepbminit( FILE* fp, int cols, int rows, int forceplain ) 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. void pbm_writepbmrow( FILE* fp, bit* bitrow, int cols, int forceplain ) Write a row from a portable bitmap. void pbm_writepbm( FILE* fp, bit** bits, int cols, int rows, int forceplain ) Write the header and all data for a portable bitmap. This function combines pbm_writepbminit() and pbm_writepbmrow(). 2 See_Also libpgm, libppm, libpnm 2 Author Copyright (C) 1989, 1991 by Tony Hansen and Jef Poskanzer. 1 pbm pbm - portable bitmap file format 2 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 fam- ily of bitmap conversion filters. The definition is as fol- lows: - A "magic number" for identifying the file type. A pbm file's magic number is the two characters "P1". - Whitespace (blanks, TABs, CRs, LFs). - A width, formatted as ASCII characters in decimal. - Whitespace. - A height, again in ASCII decimal. - Whitespace. - Width * height bits, each either '1' or '0', starting at the top-left corner of the bitmap, proceeding in normal English reading order. - The character '1' means black, '0' means white. - Whitespace in the bits section is ignored. - Characters from a "#" to the next end-of-line are ignored (comments). - No line should be longer than 70 characters. 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 pos- sible, 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 dif- ferent in the following ways: - The "magic number" is "P4" instead of "P1". - The bits are stored eight per byte, high bit first low bit last. - No whitespace is allowed in the bits section, and only a single character of whitespace (typically a newline) is allowed after the height. - The files are eight times smaller and many times faster to read and write. 2 See_Also atktopbm, brushtopbm, cmuwmtopbm, g3topbm, gemtopbm, icontopbm, macptopbm, mgrtopbm, pi3topbm, xbmtopbm, ybmtopbm, pbmto10x, pnmtoascii, pbmtoatk, pbmtobbnbg, pbmtocmuwm, pbmtoepson, pbmtog3, pbmtogem, pbmtogo, pbmtoicon, pbmtolj, pbmtomacp, pbmtomgr, pbmtopi3, pbmtoplot, pbmtoptx, pbmtox10bm, pbmtoxbm, pbmtoybm, pbmtozinc, pbmlife, pbmmake, pbmmask, pbmreduce, pbmtext, pbmupc, pnm, pgm, ppm 2 Author Copyright (C) 1989, 1991 by Jef Poskanzer. 1 bioradtopgm bioradtopgm - convert a Biorad confocal file into a portable graymap 2 Synopsis bioradtopgm [-image#] [imagedata] 2 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 . 2 Options -image# A Biorad image file may contain more than one image. With this flag, you can specify which image to extract (only one at a time). The first image in the file has number zero. If no image number is supplied, only information about the image size and the number of images in the input is printed out. No output is pro- duced. 2 Bugs A Biorad image may be in word format. If PbmPlus is not com- piled with the "BIGGRAYS" flag, word files can not be con- verted. See the Makefile. 2 See_Also pgm, pnmflip 2 Authors Copyright (C) 1993 by Oliver Trepte 1 fitstopgm fitstopgm - convert a FITS file into a portable graymap 2 Synopsis fitstopgm [-image N] [FITSfile] 2 Description Reads a FITS file as input. Produces a portable graymap as output. The results may need to be flipped top for bottom; if so, just pipe the output through pnmflip -tb. 2 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. All flags can be abbreviated to their shortest unique pre- fix. 2 References FITS stands for Flexible Image Transport System. A full description can be found in Astronomy & Astrophysics Supple- ment Series 44 (1981), page 363. 2 See_Also pgmtofits, pgm, pnmflip 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 fstopgm fstopgm - convert a Usenix FaceSaver(tm) file into a port- able graymap 2 Synopsis fstopgm [fsfile] 2 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. FaceSaver is a registered trademark of Metron Computerware Ltd. of Oakland, CA. 2 See_Also pgmtofs, pgm, pgmnorm, pnmenlarge, pnmscale, pgmtopbm 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 hipstopgm hipstopgm - convert a HIPS file into a portable graymap 2 Synopsis hipstopgm [hipsfile] 2 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. HIPS is a format developed at the Human Information Process- ing Laboratory, NYU. 2 See_Also pgm 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 lispmtopgm lispmtopgm - convert a Lisp Machine bitmap file into pgm format 2 Synopsis lispmtopgm [lispmfile] 2 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. 2 See_Also pgmtolispm, pgm 2 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. No color. 2 Author Copyright (C) 1991 by Jamie Zawinski and Jef Poskanzer. 1 pbmtopgm pbmtopgm - convert portable bitmap to portable graymap by averaging areas 2 Synopsis pbmtopgm <width> <height> [pbmfile] 2 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 simi- lar to a special case of ppmconvol. A ppmsmooth step may be needed after pbmtopgm. Pbmtopgm has the effect of anti-aliasing bitmaps which con- tain distinct line features. 2 See_Also pbm 2 Author Copyright (C) 1990 by Angus Duggan Copyright (C) 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 docu- mentation. This software is provided "as is" without express or implied warranty. 2 Notes Pbmtopgm works best with odd sample width and heights. 1 pgmbentley pgmbentley - Bentleyize a portable graymap 2 Synopsis pgmbentley [pgmfile] 2 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. 2 See_Also pgmoil, ppmrelief, pgm 2 Author Copyright (C) 1990 by Wilson Bent (whb@hoh-2.att.com) 1 pgmenhance pgmenhance - edge-enhance a portable graymap 2 Synopsis pgmenhance [-N] [pgmfile] 2 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. 2 Options The optional -N flag should be a digit from 1 to 9. 1 is the lowest level of enhancement, 9 is the highest, The default is 9. 2 See_Also pgmedge, pgm, pbm 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 pgmhist pgmhist - print a histogram of the values in a portable graymap 2 Synopsis pgmhist [pgmfile] 2 Description Reads a portable graymap as input. Prints a histogram of the gray values. 2 See_Also pgmnorm, pgm, ppmhist 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 pgmnoise pgmnoise - create a graymap made up of white noise 2 Synopsis pgmnoise width height 2 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. 2 See_Also pgm(5) 2 Author Copyright (C) 1993 by Frank Neumann 1 pgmnorm pgmnorm - normalize the contrast in a portable graymap 2 Synopsis pgmnorm [-bpercent N | -bvalue N] [-wpercent N | -wvalue N] [pgmfile] 2 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. 2 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 pre- fix. 2 See_Also pgmhist, pgm 2 Author Partially based on the fbnorm filter in Michael Mauldin's "Fuzzy Pixmap" package. Copyright (C) 1989 by Jef Poskanzer. 1 pgmoil pgmoil - turn a portable graymap into an oil painting 2 Synopsis pgmoil [-n N] [pgmfile] 2 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. 2 Options The optional -n flag controls the size of the area smeared. The default value is 3. 2 Bugs Takes a long time to run. 2 See_Also pgmbentley, ppmrelief, pgm 2 Author Copyright (C) 1990 by Wilson Bent (whb@hoh-2.att.com) 1 pgmramp pgmramp - generate a grayscale ramp 2 Synopsis pgmramp -lr|-tb | -rectangle|-ellipse width height 2 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. 2 Options -lr A left to right ramp. -tb A top to bottom ramp. -rectangle A rectangular ramp. -ellipse An elliptical ramp. All flags can be abbreviated to their shortest unique pre- fix. 2 See_Also pnmarith, pgm 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 pgmtofits pgmtofits - convert a portable graymap into FITS format 2 Synopsis pgmtofits [pgmfile] 2 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 Supple- ment Series 44 (1981), page 363. 2 See_Also fitstopgm, pgm 2 Author Copyright (C) 1989 by Wilson H. Bent (whb@hoh-2.att.com). 1 pgmtofs pgmtofs - convert portable graymap to Usenix FaceSaver(tm) format 2 Synopsis pgmtofs [pgmfile] 2 Description Reads a portable graymap as input. Produces Usenix FaceSaver(tm) format as output. FaceSaver is a registered trademark of Metron Computerware Ltd. of Oakland, CA. 2 See_Also fstopgm, pgm 2 Author Copyright (C) 1991 by Jef Poskanzer. 1 pgmtolispm pgmtolispm - convert a portable graymap into Lisp Machine format 2 Synopsis pgmtolispm [pgmfile] 2 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. 2 See_Also lispmtopgm, pgm 2 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). No color. 2 Author Copyright (C) 1991 by Jamie Zawinski and Jef Poskanzer. 1 pgmtopbm pgmtopbm - convert a portable graymap into a portable bitmap 2 Synopsis pgmtopbm [-floyd|-fs|-threshold |-dither8|-d8|-cluster3 |- c3|-cluster4|-c4 |-cluster8|-c8] [-value val] [pgmfile] 2 Description Reads a portable graymap as input. Produces a portable bit- map as output. Note that there is no pbmtopgm converter, because any pgm program can read pbm files automagically. 2 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 pre- fix. 2 References The only reference you need for this stuff is "Digital Half- toning" by Robert Ulichney, MIT Press, ISBN 0-262-21009-6. 2 See_Also pbmreduce, pgm, pbm, pnmconvol 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 psidtopgm psidtopgm - convert PostScript "image" data into a portable graymap 2 Synopsis psidtopgm width height bits/sample [imagedata] 2 Description Reads the "image" data from a PostScript file as input. Produces a portable graymap as output. This is a very simple and limited program, and is here only because so many people have asked for it. To use it you have to manually extract the readhexstring data portion from your PostScript file, and then give the width, height, and bits/sample on the command line. Before you attempt this, you should at least read the description of the "image" operator in the PostScript Language Reference Manual. It would probably not be too hard to write a script that uses this filter to read a specific variety of PostScript image, but the variation is too great to make a general- purpose reader. Unless, of course, you want to write a full-fledged PostScript interpreter... 2 See_Also pnmtops, pgm 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 spottopgm spottopgm - convert SPOT satellite images to Portable Grey- map format 2 Synopis spottopgm [-1|2|3] [Firstcol Firstline Lastcol Lastline] inputfile 2 Options -1|2|3 Extract the given colour from the SPOT image. The colours are infra-red, visible light and ultra- violet, although I don't know which corresponds to which number. If the image is in colour, this will be announced on standard error. The default colour is 1. Firstcol Firstline Lastcol Lastline Extract the specified rectangle from the SPOT image. Most SPOT images are 3000 lines long and 3000 or more columns wide. Unfortunately the SPOT format only gives the width and not the length. The width is printed on standard error. The default rectangle is the width of the input image by 3000 lines. 2 Description Spottopgm converts the named inputfile into Portable Greymap format, defaulting to the first color and the whole SPOT image unless specified by the options. 2 INSTALLATION You must edit the source program and either define BIGNDIAN or LITTLENDIAN, and fix the typedefs for uint32, uint16 and uint8 appropriately. 2 Bugs Currently spottopgm doesn't determine the length of the input file; this would involve two passes over the input file. It defaults to 3000 lines instead. Spottopgm could extract a three-color image (ppm), but I didn't feel like making the program more complicated than it is now. Besides, there is no one-to-one correspondence between red, green, blue and infra-red, visible and ultra- violet. I've only had a limited number of SPOT images to play with, and therefore wouldn't guarantee that this will work on any other images. 2 Author Warren Toomey wkt@csadfa.cs.adfa.oz.au 1 pgmcrater pgmcrater - create cratered terrain by fractal forgery 2 Synopsis pgmcrater [-number n] [-height|-ysize s] [-width|-xsize s] [-gamma g] 2 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 distri- buted 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 pix- els and lends a mellow ``telescopic image'' feel to the overall picture. 2 Options -number n Causes n craters to be generated. If no -number specification is given, 50000 craters will be gen- erated. Don't expect to see them all! For every large crater there are many, many more tiny ones which tend simply to erode the landscape. In gen- eral, the more craters you specify the more real- istic the result; ideally you want the entire ter- rain to have been extensively turned over again and again by cratering. High resolution images containing five to ten million craters are stun- ning but take quite a while to create. -height height Sets the height of the generated image to height pixels. The default height is 256 pixels. -width width Sets the width of the generated image to width pixels. The default width is 256 pixels. -xsize width Sets the width of the generated image to width pixels. The default width is 256 pixels. -ysize height Sets the height of the generated image to height pixels. The default height is 256 pixels. -gamma factor The specified factor is used to gamma correct the graymap in the same manner as performed by pnmgamma. The default value is 1.0, which results in a medium contrast image. Values larger than 1 lighten the image and reduce contrast, while values less than 1 darken the image, increasing contrast. All flags can be abbreviated to their shortest unique pre- fix. 2 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 ter- rain. 2 See_Also pgm, pnmgamma, pnmsmooth [1] Peitgen, H.-O., and Saupe, D. eds., The Science Of Fractal Images, New York: Springer Verlag, 1988. 2 Author John Walker Autodesk SA Avenue des Champs-Montants 14b CH-2074 MARIN Suisse/Schweiz/Svizzera/Svizra/Switzerland Usenet: kelvin@Autodesk.com Fax: 038/33 88 15 Voice: 038/33 76 33 software and its documentation for any purpose and without fee is hereby granted, without any conditions or restric- tions. 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 introduc- tion by James Gleick and detailed explanations by Rudy Rucker of the mathematics and algorithms used by each pro- gram. 1 pgmedge pgmedge - edge-detect a portable graymap 2 Synopsis pgmedge [pgmfile] 2 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. 2 See_Also pgmenhance, pgmtopbm, pgm, pbm 2 Author Copyright (C) 1991 by Jef Poskanzer. 1 pgmtexture pgmtexture - calculate textural features on a portable gray- map 2 Synopsis pgmtexture [-d d] [pgmfile] 2 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: (1) Angular Second Moment, (2) Contrast, (3) Correlation, (4) Variance, (5) Inverse Difference Moment, (6) Sum Average, (7) Sum Variance, (8) Sum Entropy, (9) Entropy, (10) Difference Variance, (11) Difference Entropy, (12, 13) Information Measures of Correlation, and (14) Maximal Correlation Coefficient. Algorithm taken from: Haralick, R.M., K. Shanmugam, and I. Dinstein. 1973. Tex- tural features for image classification. IEEE Transactions on Systems, Man, and Cybertinetics, SMC-3(6):610-621. 2 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. 2 References IEEE Transactions on Systems, Man, and Cybertinetics, SMC- 3(6):610-621. 2 See_Also pgm, pnmcut 2 Author Copyright (C) 1991 by Texas Agricultural Experiment Station, employer for hire of James Darrell McCauley. 1 rawtopgm rawtopgm - convert raw grayscale bytes into a portable gray- map 2 Synopsis rawtopgm [-headerskip N] [-rowskip N] [-tb|-topbottom] [width height] [imagedata] 2 Description Reads raw grayscale bytes as input. Produces a portable graymap as output. The input file is just grayscale bytes. If you don't specify the width and height on the command line, the program will check the size of the image and try to make a quadratic image of it. It is an error to supply a non quadratic image without specifying width and height. The maxval is assumed to be 255. 2 Options -headerskip If the file has a header, you can use this flag to skip over it. -rowskip If there is padding at the ends of the rows, you can skip it with this flag. Note that rowskip can be a real number. Amazingly, I once had an image with 0.376 bytes of padding per row. This turned out to be due to a file-transfer problem, but I was still able to read the image. -tb -topbottom Flips the image upside down. The first pixel in a pgm file is in the lower left corner of the image. For conversion from images with the first pixel in the upper left corner (e.g. the Molecular Dynamics and Leica confocal formats) this flips the image right. This is equivalent to rawtopgm [file] | pnmflip -tb . 2 Bugs If you don't specify the image width and height, the program will try to read the entire image to a memory buffer. If you get a message that states that you are out of memory, try to specify the width and height on the command line. Also, the -tb option consumes much memory. 2 See_Also pgm, rawtoppm, pnmflip 2 Authors Copyright (C) 1989 by Jef Poskanzer. Modified June 1993 by Oliver Trepte, oliver@fysik4.kth.se 1 pnmarith pnmarith - perform arithmetic on two portable anymaps 2 Synopsis pnmarith -add|-subtract|-multiply| pnmfile1 pnmfile2 2 Description Reads two portable anymaps as input. Performs the specified arithmetic operation, and produces a portable anymap as out- put. 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 pre- fix. 2 See_Also pbmmask, pnmpaste, pnminvert, pnm 2 Author Copyright (C) 1989, 1991 by Jef Poskanzer. Lightly modified by Marcel Wijkstra <wijkstra@fwi.uva.nl> 1 pnmcat pnmcat - concatenate portable anymaps 2 Synopsis pnmcat [-white|-black] -leftright|-lr [-jtop|-jbottom] pnmfile pnmfile ... pnmcat [-white|-black] -topbottom|-tb [-jleft|-jright] pnmfile pnmfile ... 2 Description Reads portable anymaps as input. Concatenates them either left to right or top to bottom, and produces a portable anymap as output. 2 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. All flags can be abbreviated to their shortest unique pre- fix. 2 See_Also pnm 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 pnmcomp pnmcomp - composite two portable anymap files together 2 Synopsis pnmcomp [-invert] [-xoffN] [-yoffN] [-alphapgmfile] overlay [pnm-input] [pnm-output] 2 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. 2 See_Also pnm 2 Author Copyright (C) 1992 by David Koblas (koblas@mips.com). 1 pnmconvol pnmconvol - general MxN convolution on a portable anymap 2 Synopsis pnmconvol convolutionfile [pnmfile] 2 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 aver- age of the nearby pixels. The weights and the area to aver- age 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. How- ever, if you want to use a pixmap and do a different convo- lution to different colors, you can certainly do that. 2 See_Also pnmsmooth, pnm 2 Author Copyright (C) 1989, 1991 by Jef Poskanzer. 1 pnmcrop pnmcrop - crop a portable anymap 2 Synopsis pnmcrop [-white|-black] [pnmfile] 2 Description Reads a portable anymap as input. Removes edges that are the background color, and produces a portable anymap as out- put. 2 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. All flags can be abbreviated to their shortest unique pre- fix. 2 See_Also pnmcut, pnm 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 pnmcut pnmcut - cut a rectangle out of a portable anymap 2 Synopsis pnmcut x y width height [pnmfile] 2 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, respec- tively. 2 See_Also pnm 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 pnmdepth pnmdepth - change the maxval in a portable anymap 2 Synopsis pnmdepth newmaxval [pnmfile] 2 Description Reads a portable anymap as input. Scales all the pixel values, and writes out the image with the new maxval. Scal- ing 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 max- val. For instance, if you want the color values to be five bits wide, use a maxval of 31, not 32. 2 See_Also pnm, ppmquant, ppmdither 2 Author Copyright (C) 1989, 1991 by Jef Poskanzer. 1 pnmenlarge pnmenlarge - read a portable anymap and enlarge it N times 2 Synopsis pnmenlarge N [pnmfile] 2 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. 2 See_Also pbmreduce, pnmscale, pnmsmooth, pnm 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 pnmfile pnmfile - describe a portable anymap 2 Synopsis pnmfile [pnmfile] ... 2 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 par- ticularly pretty. 2 See_Also pnm, file 2 Author Copyright (C) 1991 by Jef Poskanzer. 1 pnmflip pnmflip - perform one or more flip operations on a portable anymap 2 Synopsis pnmflip [-leftright|-lr] [-topbottom|-tb] [-transpose|-xy] [-rotate90|-r90|-ccw ] [-rotate270|-r270|-cw ] [- rotate180|-r180] [pnmfile] 2 Description Reads a portable anymap as input. Performs one or more flip operations, in the order specified, and writes out a port- able anymap. 2 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. All flags can be abbreviated to their shortest unique pre- fix. 2 See_Also pnmrotate, pnm 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 pnminvert pnminvert - invert a portable anymap 2 Synopsis pnminvert [pnmfile] 2 Description Reads a portable anymap as input. Inverts it black for white and produces a portable anymap as output. 2 See_Also pnm 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 pnmnoraw pnmnoraw - force a portable anymap into plain format 2 Synopsis pnmnoraw [pnmfile] 2 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 PBMPLUSAWBITS compile-time option. 2 See_Also pnm 2 Author Copyright (C) 1991 by Jef Poskanzer. 1 pnmpad pnmpad - add borders to portable anymap 2 Synopsis pnmpad [-white|-black] [-l#] [-r#] [-t#] [-b#] [pnmfile] 2 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). 2 See_Also pbmmake, pnmpaste, pbm 2 Author Copyright (C) 1990 by Angus Duggan Copyright (C) 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 docu- mentation. This software is provided "as is" without express or implied warranty. 1 pnmpaste pnmpaste - paste a rectangle into a portable anymap 2 Synopsis pnmpaste [-replace|-or|-and |-xor] frompnmfile x y [intopnmfile] 2 Description Reads two portable anymaps as input. Inserts the first anymap into the second at the specified location, and pro- duces a portable anymap the same size as the second as out- put. 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 bit- maps. These operations act as if white is TRUE and black is FALSE. All flags can be abbreviated to their shortest unique pre- fix. 2 See_Also pnmcut, pnminvert, pnmarith, pnm, pbmmask 2 Author Copyright (C) 1989, 1991 by Jef Poskanzer. 1 pnmscale pnmscale - scale a portable anymap 2 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] 2 Description Reads a portable anymap as input. Scales it by the speci- fied 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 pre- fix. 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. 2 See_Also pbmreduce, pnmenlarge, pnmsmooth, pnm 2 Author Copyright (C) 1989, 1991 by Jef Poskanzer. 1 pnmtile pnmtile - replicate a portable anymap into a specified size 2 Synopsis pnmtile width height [pnmfile] 2 Description Reads a portable anymap as input. Replicates it until it is the specified size, and produces a portable anymap as out- put. 2 See_Also pnm 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 pnmtoddif pnmtoddif - Convert a portable anymap to DDIF format 2 Synopis pnmtoddif pnmtoddif [-resolution x y] [pnmfile [ddiffile]] 2 Description pnmtoddif takes a portable anymap from standard input and converts it into a DDIF image file on standard output or the specified DDIF file. pbm format (bitmap) data is written as 1 bit DDIF, pgm for- mat data (greyscale) as 8 bit greyscale DDIF, and ppm format data is written as 8,8,8 bit color DDIF. All DDIF image files are written as uncompressed. The data plane organiza- tion is interleaved by pixel. In addition to the number of pixels in the width and height dimension, DDIF images also carry information about the size that the image should have, that is, the physical space that a pixel occupies. PBMPLUS images do not carry this informa- tion, hence it has to be externally supplied. The default of 78 dpi has the beneficial property of not causing a resize on most Digital Equipment Corporation color monitors. 2 Options resolution The horizontal and vertical resolution of the output image in dots per inch. Defaults to 78 dpi. pnmfile The filename for the image file in pnm for- mat. If this argument is omitted, input is read from stdin. ddiffile The filename for the image file to be created in DDIF format. If this argument is omitted, the ddiffile is written to standard output. It can only specified if a pnmfile is also specified. 2 Author Burkhard Neidecker-Lutz Digital Equipment Corporation, CEC Karlsruhe neideck@nestvx.enet.dec.com 1 pnmtops pnmtops - convert portable anymap to PostScript 2 Synopsis pnmtops [-scale s] [-turn|-noturn] [-rle|-runlength] [-dpi n] [-width n] [-height n] [pnmfile] 2 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 pack- age, it comes with a pstoppm script. 2 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 compres- sion. 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. All flags can be abbreviated to their shortest unique pre- fix. 2 See_Also pnm, psidtopgm 2 Author Copyright (C) 1989, 1991 by Jef Poskanzer. 1 pnmtorast pnmtorast - convert a portable pixmap into a Sun rasterfile 2 Synopsis pnmtorast [-standard|-rle] [pnmfile] 2 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. 2 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. All flags can be abbreviated to their shortest unique pre- fix. 2 See_Also rasttopnm, pnm 2 Author Copyright (C) 1989, 1991 by Jef Poskanzer. 1 pnmtoxwd pnmtoxwd - convert a portable anymap into an X11 window dump 2 Synopsis pnmtoxwd [-pseudodepth n] [-directcolor] [pnmfile] 2 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. 2 See_Also xwdtopnm, pnm, xwud 2 Author Copyright (C) 1989, 1991 by Jef Poskanzer. 1 rasttopnm rasttopnm - convert a Sun rasterfile into a portable anymap 2 Synopsis rasttopnm [rastfile] 2 Description Reads a Sun rasterfile as input. Produces a portable anymap as output. The type of the output file depends on the input file - if it's black & white, a pbm file is written, else if it's grayscale a pgm file, else a ppm file. The program tells you which type it is writing. 2 See_Also pnmtorast, pnm 2 Author Copyright (C) 1989, 1991 by Jef Poskanzer. 1 xwdtopnm xwdtopnm - convert a X11 or X10 window dump file into a portable anymap 2 Synopsis xwdtopnm [xwdfile] 2 Description Reads a X11 or X10 window dump file as input. Produces a portable anymap as output. The type of the output file depends on the input file - if it's black & white, a pbm file is written, else if it's grayscale a pgm file, else a ppm file. The program tells you which type it is writing. Using this program, you can convert anything on an X workstation's screen into an anymap. Just display whatever you're interested in, do an xwd, run it through xwdtopnm, and then use pnmcut to select the part you want. 2 Bugs I haven't tested this tool with very many configurations, so there are probably bugs. Please let me know if you find any. 2 See_Also pnmtoxwd, pnm, xwd 2 Author Copyright (C) 1989, 1991 by Jef Poskanzer. 1 zeisstopnm zeisstopnm - convert a Zeiss confocal file into a portable anymap 2 Synopsis zeisstopnm [-pgm | -ppm] [zeissfile] 2 Description Reads a Zeiss confocal file as input. Produces a portable anymap as output. The type of the output file depends on the input file - if it's grayscale a pgm file, else a ppm file will be produced. The program tells you which type it is writing. 2 Options -pgm Force the output to be a pgm file. -ppm Force the output to be a ppm file. 2 See_Also pnm 2 Author Copyright (C) 1993 by Oliver Trepte 1 pnmgamma pnmgamma - perform gamma correction on a portable anymap 2 Synopsis pnmgamma value [pnmfile] pnmgamma redvalue greenvalue bluevalue [pnmfile] 2 Description Reads a portable anymap as input. Performs gamma correc- tion, 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. 2 See_Also pnm 2 Author Copyright (C) 1991 by Bill Davidson and Jef Poskanzer. 1 pnmhistmap pnmhistmap - draw a histogram for a PGM or PPM file 2 Synopsis pnmhistmap [-black] [-white] [-max N] [-verbose] [pnmfile] 2 Description Reads a portable anymap as input, although bitmap (PBM) input produces an error message and no image. Produces an image showing a histogram of the color (or gray) values in the input. A graymap (PGM) input produces a bitmap output. A pixmap (PPM) input produces pixmap output with three over- laid histograms: a red one for the red input, a green one for the green input, and a blue one for the blue input. The output is fixed in size: 256 pixels wide by 200 pixels high. 2 Options -black Ignores the count of black pixels when scaling the his- togram. -white Ignores the count of white pixels when scaling the his- togram. The -black and -white options, which can be used seperately or together, are useful for images with a large percentage of pixels whose value is zero or 255, which can cause the remaining histogram data to become unreadbaly small. Note that, for pixmap inputs, these options apply to all colors; if, for example, the input has a large number of bright-red areas, you will probably want to use the -white option. -max N Force the scaling of the histogram to use N as the largest-count value. This is useful for inputs with a large percentage of single-color pixels which are not black or white. -verbose Report the progress of making the histogram, including the largest-count value used to scale the output. All flags can be abbreviated to their shortest unique pre- fix. 2 Bugs Assumes maxval is always 255. Images with a smaller maxval will only use the lower-value side of the histogram. This can be overcome either by piping the input through "pnmdepth 255" or by cutting and scaling the lower-value side of the histogram. Neither is a particularly elegant solution. Should allow the output size to be specified. 2 See_Also pgmhist(1), ppmhist(1), pgm(5), ppm(5) 2 Author Wilson H. Bent. Jr. (whb@usc.edu). 1 pnmnlfilt pnmnlfilt - non-linear filters: smooth, alpha trim mean, optimal estimation smoothing, edge enhancement. 2 Synopsis pnmnlfilt alpha radius [pnmfile] 2 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 (ie. 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 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 (ie. 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 This type of filter applies a smoothing filter adaptively over the image. For each pixel the variance of the sur- rounding 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 con- trols the effective radius, but it probably advisable to leave the radius between 0.8 and 1.0 for the variance calcu- lation 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 >= 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 enhance- ment is the direct opposite of smoothing. For reducing color quantization noise in images (ie. 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 pos- sibly 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. 2 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 "Con- verting 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, 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. 2 See_Also pgmenhance, pnmconvol, pnm 2 Bugs Integers and tables may overflow if PPM_MAXMAXVAL is greater than 255. 2 Author Graeme W. Gill graeme@labtam.oz.au 1 pnmrotate pnmrotate - rotate a portable anymap by some angle 2 Synopsis pnmrotate [-noantialias] angle [pnmfile] 2 Description Reads a portable anymap as input. Rotates it by the speci- fied 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 pnmro- tate 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 pix- els. 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 modi- fied. 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 pre- fix. 2 References "A Fast Algorithm for General Raster Rotation" by Alan Paeth, Graphics Interface '86, pp. 77-81. 2 See_Also pnmshear, pnmflip, pnm, ppmquant 2 Author Copyright (C) 1989, 1991 by Jef Poskanzer. 1 pnmshear pnmshear - shear a portable anymap by some angle 2 Synopsis pnmshear [-noantialias] angle [pnmfile] 2 Description Reads a portable anymap as input. Shears it by the speci- fied 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 pix- els 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 pre- fix. 2 See_Also pnmrotate, pnmflip, pnm, ppmquant 2 Author Copyright (C) 1989, 1991 by Jef Poskanzer. 1 tifftopnm tifftopnm - convert a TIFF file into a portable anymap 2 Synopsis tifftopnm [-headerdump] tifffile 2 Description Reads a TIFF file as input. Produces a portable anymap as output. The type of the output file depends on the input file - if it's black & white, a pbm file is written, else if it's grayscale a pgm file, else a ppm file. The program tells you which type it is writing. 2 Options -headerdump Dump TIFF file information to stderr. This information may be useful in debugging TIFF file conversion prob- lems. All flags can be abbreviated to their shortest unique pre- fix. 2 See_Also pnmtotiff, pnm 2 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. 2 Author Derived by Jef Poskanzer from tif2ras.c, which is Copyright (c) 1990 by Sun Microsystems, Inc. Author: Patrick J. Naughton (naughton@wind.sun.com). 1 pnmtotiff pnmtotiff - convert a a portable anymap into a TIFF file 2 Synopsis pnmtotiff [-none|-packbits| -lzw|-g3|-g4] [-2d] [-fill] [- predictor n] [-msb2lsb|-lsb2msb] [-rowsperstrip n] [pnmfile] 2 Description Reads a portable anymap as input. Produces a TIFF file as output. 2 Options By default, pnmtotiff creates a TIFF file with LZW compres- sion. 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. 2 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. 2 See_Also tifftopnm, pnm 2 Author Derived by Jef Poskanzer from ras2tiff.c, which is Copyright (c) 1990 by Sun Microsystems, Inc. Author: Patrick J. Naughton (naughton@wind.sun.com). 1 libpnm libpnm - functions to support portable anymap programs 2 Synopsis #include <pnm.h> cc ... libpnm.a libppm.a libpgm.a libpbm.a 2 Description TYPES AND CONSTANTS typedef ... xel; typedef ... xelval; #define PNM_MAXMAXVAL ... extern xelval pnm_pbmmaxval; Each xel contains three xelvals, each of which should con- tain 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. XEL MANIPULATIONS xelval PNM_GET1( xel x ) 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(). void PNM_ASSIGN1( xel x, xelval v ) 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(). int PNM_EQUAL( xel x, xel y ) This macro checks two xels for equality. int PNM_FORMAT_TYPE( int format ) For distinguishing different file types. INITIALIZATION void pnm_init( int* argcP, char* argv[] ) All PNM programs must call this routine. MEMORY MANAGEMENT xel** pnm_allocarray( int cols, int rows ) Allocate an array of xels. xel* pnm_allocrow( int cols ) Allocate a row of the given number of xels. void pnm_freearray( xel** xels, int rows ) Free the array allocated with pnmllocarray() containing the given number of rows. void pnm_freerow( xel* xelrow ) Free a row of xels. READING FILES 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 allo- cated array and filling in the rows, cols, maxval, and for- mat 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. WRITING FILES 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 ) Write a row from a portable anymap. 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(). FORMAT PROMOTION 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 ) Promote an entire anymap. XEL MANIPULATION xel pnm_whitexel( xelval maxval, int format ) xel pnm_blackxel( xelval maxval, int format ) Return a white or black xel for the given maxval and format. void pnm_invertxel( xel* x, xelval maxval, int format ) Invert an xel. xel pnm_backgroundxelrow( xel* xelrow, int cols, xelval maxval, int format ) Figure out an appropriate background xel based on this row. 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(). 2 See_Also pbm, pgm, ppm 2 Author Copyright (C) 1989, 1991 by Tony Hansen and Jef Poskanzer. 1 pnm pnm - portable anymap file format 2 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. 2 See_Also anytopnm, rasttopnm, tifftopnm, xwdtopnm, pnmtops, pnmtorast, pnmtotiff, pnmtoxwd, pnmar- ith, pnmcat, pnmconvol, pnmcrop, pnmcut, pnmdepth, pnmenlarge, pnmfile, pnmflip, pnmgamma, pnmindex, pnminvert, pnmmargin, pnmnoraw, pnmpaste, pnmrotate, pnmscale, pnmshear, pnmsmooth, pnmtile, ppm, pgm, pbm 2 Author Copyright (C) 1989, 1991 by Jef Poskanzer. 1 bmptoppm bmptoppm - convert a BMP file into a portable pixmap 2 Synopsis bmptoppm [bmpfile] 2 Description Reads a Microsoft Windows or OS/2 BMP file as input. Pro- duces a portable pixmap as output. 2 See_Also ppmtobmp, ppm 2 Author Copyright (C) 1992 by David W. Sanderson. 1 gouldtoppm gouldtoppm - convert Gould scanner file into a portable pix- map 2 Synopsis gouldtoppm [gouldfile] 2 Description Reads a file produced by the Gould scanner as input. Pro- duces a portable pixmap as output. 2 See_Also ppm 2 Author Copyright(C) 1990 by Stephen Paul Lesniewski 1 ilbmtoppm ilbmtoppm - convert an ILBM file into a portable pixmap 2 Synopsis ilbmtoppm [-verbose] [ILBMfile] 2 Description Reads an IFF ILBM file as input. Produces a portable pixmap as output. Supported ILBM types are: Normal ILBMs with 1-16 planes. Amiga Extra-Halfbrite (EHB) Amiga Hold-and-modify (HAM) with 3-16 planes. 24 bit. Color map (BMHD + CMAP chunk only, nPlanes = 0). Unofficial direct color. 1-16 planes for each color component. Chunks used: BMHD, CMAP, CAMG (only HAM & EHB flags used), BODY unofficial DCOL chunk to identify direct color ILBM Chunks ignored: GRAB, DEST, SPRT, CRNG, CCRT, CLUT, DPPV, DRNG, EPSF Other chunks (ignored but displayed in verbose mode): NAME, AUTH, (c), ANNO, DPI Unknown chunks are skipped. 2 Options -verbose Give some informaton about the ILBM file. 2 Bugs Probably. 2 References Amiga ROM Kernel Reference Manual - Devices (3rd Ed.) Addison Wesley, ISBN 0-201-56775-X 2 See_Also ppm(5), ppmtoilbm(1) 2 Authors Copyright (C) 1989 by Jef Poskanzer. Modified June 1993 by Ingo Wilken (Ingo.Wilken@informatik.uni-oldenburg.de) 1 imgtoppm imgtoppm - convert an Img-whatnot file into a portable pix- map 2 Synopsis imgtoppm [imgfile] 2 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. 2 See_Also ppm 2 Author Based on a simple conversion program posted to comp.graphics by Ed Falk. Copyright (C) 1989 by Jef Poskanzer. 1 mtvtoppm mtvtoppm - convert output from the MTV or PRT ray tracers into a portable pixmap 2 Synopsis mtvtoppm [mtvfile] 2 Description Reads an input file from Mark VanDeWettering's MTV ray tracer. Produces a portable pixmap as output. The PRT raytracer also produces this format. 2 See_Also ppm 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 pcxtoppm pcxtoppm - convert a PCX file into a portable pixmap 2 Synopsis pcxtoppm [pcxfile] 2 Description Reads a PCX file as input. Produces a portable pixmap as output. 2 See_Also ppmtopcx, ppm 2 Author Copyright (C) 1990 by Michael Davidson. 1 pgmtoppm pgmtoppm - colorize a portable graymap into a portable pix- map 2 Synopsis pgmtoppm colorspec [pgmfile] pgmtoppm colorspec1-colorspec2 [pgmfile] pgmtoppm -map mapfile [pgmfile] 2 Description Reads a portable graymap as input. Colorizes it by multi- plying 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: o A name, assuming that a pointer to an X11-style color names file was compiled in. o An X11-style hexadecimal specifier: rgb:r/g/b, where r g and b are each 1- to 4-digit hexadecimal numbers. o An X11-style decimal specifier: rgbi:r/g/b, where r g and b are floating point numbers between 0 and 1. o For backwards compatibility, an old-X11-style hexade- cimal number: #rgb, #rrggbb, #rrrgggbbb, or #rrrrggggbbbb. o For backwards compatibility, a triplet of numbers separated by commas: r,g,b, where r g and b are float- ing point numbers between 0 and 1. (This style was added before MIT came up with the similar rgbi style.) 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. 2 See_Also rgb3toppm, ppmtopgm, ppmtorgb3, ppm, pgm 2 Author Copyright (C) 1991 by Jef Poskanzer. 1 pi1toppm pi1toppm - convert an Atari Degas .pi1 into a portable pix- map 2 Synopsis pi1toppm [pi1file] 2 Description Reads an Atari Degas .pi1 file as input. Produces a port- able pixmap as output. 2 See_Also ppmtopi1, ppm, pi3topbm, pbmtopi3 2 Author Copyright (C) 1991 by Steve Belczyk (seb3@gte.com) and Jef Poskanzer. 1 picttoppm picttoppm - convert a Macintosh PICT file into a portable pixmap 2 Synopsis picttoppm [-verbose] [-fullres] [-noheader] [pictfile] 2 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. 2 Options -fullres Force any images in the PICT file to be output with at least their full resolution. A PICT file may indicate that a contained image is to be scaled down before out- put. This option forces images to retain their sizes and prevent information loss. -noheader Do not skip the 512 byte header that is present on all PICT files. This is useful when you have PICT data that was not stored in the data fork of a PICT file. -verbose Turns on verbose mode which prints a a whole bunch of information that only picttoppm hackers really care about. 2 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. 2 See_Also Inside Macintosh volume 5, ppmtopict, ppm 2 Author Copyright 1989 George Phillips 1 pjtoppm pjtoppm - convert an HP PaintJet file to a portable pixmap 2 Synopsis pjtoppm [paintjet] 2 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 con- vert most raster image files. REFERENCES HP PaintJet XL Color Graphics Printer User's Guide 2 See_Also ppmtopj 2 Author Copyright (C) 1991 by Christos Zoulas. 1 ppm3d ppm3d - convert two portable pixmap into a red/blue 3d glasses pixmap 2 Synopsis ppm3d leftppmfile rightppmfile [horizontal offset] 2 Description Reads two portable pixmaps as input. Produces a portable pixmap as output, with the images overlapping by horizontal offset pixels in blue/red format. horizontal offset defaults to 30 pixels. Pixmaps MUST be the same size. 2 See_Also ppm(5) 2 Author Copyright (C) 1993 by David K. Drum. 1 ppmbrighten ppmbrighten - change an images Saturation and Value from an HSV map 2 Synopsis ppmbrighten [-n] [-s <+- saturation>] [-v <+- value>] <ppmfile> 2 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 ppmbrighten -v 100 to add 100 percent to the Value. The 'n' option normalizes the Value to exist between 0 and 1 (normalized). 2 See_Also pgmnorm, ppm 2 Notes This program does not change the number of colors. 2 Author Copyright (C) 1990 by Brian Moffet Copyright (C) 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 docu- mentation. This software is provided "as is" without express or implied warranty. 1 ppmchange ppmchange - change all pixels of one color to another in a portable pixmap 2 Synopsis ppmchange colorspec1 colorspec2 [ppmfile] 2 Description Reads a portable pixmap as input. Changes all pixels of colorspec1 to colorspec2, leaving all others unchanged. The color can be specified in five ways: o A name, assuming that a pointer to an X11-style color names file was compiled in. o An X11-style hexadecimal specifier: rgb:r/g/b, where r g and b are each 1- to 4-digit hexadecimal numbers. o An X11-style decimal specifier: rgbi:r/g/b, where r g and b are floating point numbers between 0 and 1. o For backwards compatibility, an old-X11-style hexade- cimal number: #rgb, #rrggbb, #rrrgggbbb, or #rrrrggggbbbb. o For backwards compatibility, a triplet of numbers separated by commas: r,g,b, where r g and b are float- ing point numbers between 0 and 1. (This style was added before MIT came up with the similar rgbi style.) 2 See_Also pgmtoppm(1), ppm(5) 2 Author Wilson H. Bent. Jr. (whb@usc.edu) 1 ppmdim ppmdim - dim a portable pixmap down to total blackness 2 Synopsis ppmdim dimfactor [ppmfile] 2 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. ppmdim is similar to ppmbrighten , but not exactly the same. 2 See_Also ppm(5), ppmflash(1), pnmgamma(1), ppmbrighten(1) 2 Author Copyright (C) 1993 by Frank Neumann 1 ppmdist ppmdist - simplistic grayscale assignment for machine generated, color images 2 Synopsis ppmdist [-intensity|-frequency] [ppmfile] 2 Description Reads a portable pixmap as input, performs a simplistic grayscale assignment intended for use with grayscale or bit- map printers. Often conversion from ppm to pgm will yield an image with contrast too low for good printer output. The program max- imizes 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). 2 Options Helpful only for images with a very small number of colors. Perhaps should have been an option to ppmtopgm. 2 See_Also ppmtopgm, ppmhist, ppm 2 Author Copyright (C) 1993 by Dan Stromberg. 1 ppmdither ppmdither - ordered dither for color images 2 Synopsis ppmdither [-dim dimension] [-red shades] [-green shades] [- blue shades] [ppmfile] 2 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. 2 Options -dim dimension The size of the dithering matrix. Must be a power of 2. -red shades The number of red shades to be used; minimum of 2. -green shades The number of green shades to be used; minimum of 2. -blue shades The number of blue shades to be used; minimum of 2. 2 See_Also pnmdepth, ppmquant, ppm 2 Author Copyright (C) 1991 by Christos Zoulas. 1 ppmflash ppmflash - brighten a picture up to complete white-out 2 Synopsis ppmflash flashfactor [ppmfile] 2 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. This program is similar to ppmbrighten, but not exactly the same. 2 See_Also ppm(5), ppmdim(1), pnmgamma(1), ppmbrighten(1) 2 Author Copyright (C) 1993 by Frank Neumann 1 ppmhist ppmhist - print a histogram of a portable pixmap 2 Synopsis ppmhist [ppmfile] 2 Description Reads a portable pixmap as input. Generates a histogram of the colors in the pixmap. 2 See_Also ppm, pgmhist 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 ppmmake ppmmake - create a pixmap of a specified size and color 2 Synopsis ppmmake color width height 2 Description Produces a portable pixmap of the specified color, width, and height. The color can be specified in five ways: o A name, assuming that a pointer to an X11-style color names file was compiled in. o An X11-style hexadecimal specifier: rgb:r/g/b, where r g and b are each 1- to 4-digit hexadecimal numbers. o An X11-style decimal specifier: rgbi:r/g/b, where r g and b are floating point numbers between 0 and 1. o For backwards compatibility, an old-X11-style hexade- cimal number: #rgb, #rrggbb, #rrrgggbbb, or #rrrrggggbbbb. o For backwards compatibility, a triplet of numbers separated by commas: r,g,b, where r g and b are float- ing point numbers between 0 and 1. (This style was added before MIT came up with the similar rgbi style.) 2 See_Also ppm, pbmmake 2 Author Copyright (C) 1991 by Jef Poskanzer. 1 ppmmix ppmmix - blend together two portable pixmaps 2 Synopsis ppmmix fadefactor ppmfile1 ppmfile2 2 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. The two pixmaps must have the same size. 2 See_Also ppm(5) 2 Author Copyright (C) 1993 by Frank Neumann 1 ppmquant ppmquant - quantize the colors in a portable pixmap down to a specified number 2 Synopsis ppmquant [-floyd|-fs] ncolors [ppmfile] ppmquant [-floyd|-fs] -map mapfile [ppmfile] 2 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 speci- fying your own set of colors with the -map flag. The map- file 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 diffu- sion 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 pre- fix. 2 References "Color Image Quantization for Frame Buffer Display" by Paul Heckbert, SIGGRAPH '82 Proceedings, page 297. 2 See_Also ppmquantall, pnmdepth, ppmdither, ppm 2 Author Copyright (C) 1989, 1991 by Jef Poskanzer. 1 ppmrelief ppmrelief - run a Laplacian relief filter on a portable pixmap 2 Synopsis ppmrelief [ppmfile] 2 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 Photog- raphy" by Holzmann, equation 3.19. It's a sort of edge- detection. 2 See_Also pgmbentley, pgmoil, ppm 2 Author Copyright (C) 1990 by Wilson Bent (whb@hoh-2.att.com) 1 ppmshift ppmshift - shift lines of a portable pixmap left or right by a random amount 2 Synopsis ppmshift shift [ppmfile] 2 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. 2 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: # 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. 2 See_Also ppm(5), pnmcut(1), pnmflip(1), ppmdim(1), pnmcat(1) 2 Author Copyright (C) 1993 by Frank Neumann 1 ppmspread ppmspread - displace a portable pixmap's pixels by a random amount 2 Synopsis ppmspread amount [ppmfile] 2 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 ). 2 See_Also ppm(5), pnmconvol(1) 2 Author Copyright (C) 1993 by Frank Neumann 1 ppmtoacad ppmtoacad - convert portable pixmap to AutoCAD database or slide 2 Synopsis ppmtoacad [-dxb] [-poly] [-background colour] [-white] [- aspect ratio] [-8] [ppmfile] 2 Description Reads a portable pixmap as input. Produces an AutoCAD(Reg.) slide file or binary database import (.dxb) file as output. If no ppmfile is specified, input is read from standard input. 2 Options -dxb An AutoCAD binary database import (.dxb) file is writ- ten. This file is read with the DXBIN command and, once loaded, becomes part of the AutoCAD geometrical database and can be viewed and edited like any other object. Each sequence of identical pixels becomes a separate object in the database; this can result in very large AutoCAD drawing files. However, if you want to trace over a bitmap, it lets you zoom and pan around the bitmap as you wish. -poly If the -dxb option is not specified, the output of ppmtoacad is an AutoCAD slide file. Normally each row of pixels is represented by an AutoCAD line entity. If -poly is selected, the pixels are rendered as filled polygons. If the slide is viewed on a display with higher resolution than the source pixmap, this will cause the pixels to expand instead of appearing as discrete lines against the screen background colour. Regrettably, this representation yields slide files which occupy more disc space and take longer to display. -background colour Most AutoCAD display drivers can be configured to use any available colour as the screen background. Some users perfer a black screen background, others white, while splinter groups advocate burnt ocher, tawny puce, and shocking grey. Discarding pixels whose closest AutoCAD colour representation is equal to the back- ground colour can substantially reduce the size of the AutoCAD database or slide file needed to represent a bitmap. If no -background colour is specified, the screen background colour is assumed to be black. Any AutoCAD colour number may be specified as the screen background; colour numbers are assumed to specify the hues defined in the standard AutoCAD 256 colour palette. -white Since many AutoCAD users choose a white screen back- ground, this option is provided as a short-cut. Speci- fying -white is identical in effect to -background 7. -aspect ratio If the source pixmap had non-square pixels, the ratio of the pixel width to pixel height should be specified as ratio. The resulting slide or .dxb file will be corrected so that pixels on the AutoCAD screen will be square. For example, to correct an image made for a 320x200 VGA/MCGA screen, specify -aspect 0.8333. -8 Restricts the colours in the output file to the 8 RGB shades. All flags can be abbreviated to their shortest unique pre- fix. 2 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. 2 See_Also AutoCAD Reference Manual: Slide File Format and Binary Draw- ing Interchange (DXB) Files, ppm 2 Author John Walker Autodesk SA Avenue des Champs-Montants 14b CH-2074 MARIN Suisse/Schweiz/Svizzera/Svizra/Switzerland Usenet: kelvin@Autodesk.com Fax: 038/33 88 15 Voice: 038/33 76 33 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 restric- tions. This software is provided ``as is'' without express or implied warranty. AutoCAD and Autodesk are registered trademarks of Autodesk, Inc. 1 ppmtobmp ppmtobmp - convert a portable pixmap into a BMP file 2 Synopsis ppmtobmp [-windows] [-os2] [ppmfile] 2 Description Reads a portable pixmap as input. Produces a Microsoft Win- dows or OS/2 BMP file as output. 2 Options -windows Tells the program to produce a Microsoft Windows BMP file. -os2 Tells the program to produce an OS/2 BMP file. (This is the default.) All flags can be abbreviated to their shortest unique pre- fix. 2 See_Also bmptoppm, ppm 2 Author Copyright (C) 1992 by David W. Sanderson. 1 ppmtogif ppmtogif - convert a portable pixmap into a GIF file 2 Synopsis ppmtogif [-interlace] [-sort] [-map mapfile ] [ppmfile] 2 Description Reads a portable pixmap as input. Produces a GIF file as output. 2 Options -interlace Tells the program to produce an interlaced GIF file. -sort Produces a GIF file with a sorted color map. -map mapfile Uses the colors found in the mapfile to create the colormap in the GIF file, instead of the colors from ppmfile. The mapfile can be any ppm file; all that matters is the colors in it. If the colors in ppmfile do not match those in mapfile , they are matched to a "best match". A (much) better result can be obtained by using the following filter in advance: ppmquant -floyd -map mapfile All flags can be abbreviated to their shortest unique pre- fix. 2 See_Also giftopnm, ppmquant, ppm 2 Author Based on GIFENCOD by David Rowley <mgardi@watdcsu.waterloo.edu>. Lempel-Ziv compression based on "compress". Copyright (C) 1989 by Jef Poskanzer. 1 ppmtoicr ppmtoicr - convert a portable pixmap into NCSA ICR format 2 Synopsis ppmtoicr [-windowname name] [-expand expand] [-display display] [-rle] [ppmfile] 2 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. 2 Options -windownamename Output will be displayed in name (Default is to use ppmfile or "untitled" if standard input is read.) -expandexpand Output will be expanded on display by factor expand (For example, a value of 2 will cause four pixels to be displayed for every input pixel.) -displaydisplay Output will be displayed on screen numbered display -rle Use run-length encoded format for display. (This will nearly always result in a quicker display, but may skew the colormap.) 2 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: giftopnm giffile | ppmtoicr -w giffile -r -e 2 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. 2 See_Also ppm NCSA Telnet for the Macintosh, University of Illinois at Urbana-Champaign (1989) 2 Author Copyright (C) 1990 by Kanthan Pillay (svpillay@Princeton.EDU), Princeton University Computing and Information Technology. 1 ppmtoilbm ppmtoilbm - convert a portable pixmap into an ILBM file 2 Synopsis ppmtoilbm [-maxplanes|-mp N] [-fixplanes|-fp N] [-ham6|- ham8] [-dcbits|-dcplanesrg [-normal|-hamif|-hamforce - dcif|-dcforce|-cmaponly] [-ecs|-aga] [-mapppmfile] [ppmfile] 2 Description Reads a portable pixmap as input. Produces an ILBM file as output. Supported ILBM types are: Normal ILBMs with 1-16 planes. Amiga Hold-and-modify (HAM) with 3-16 planes. 24 bit. Color map (BMHD + CMAP chunk only, nPlanes = 0). Unofficial direct color. 1-16 planes for each color component. Chunks written: BMHD, CMAP, CAMG (only for HAM), BODY (not for colormap files) unofficial DCOL chunk for direct color ILBM 2 Options Options marked with (*) can be prefixed with a "no", e.g. "-nohamif". All options can be abbreviated to their shortest unique prefix. -maxplanes | -mp n (default 5, minimum 1, maximum 16) Maximum planes to write in a normal ILBM. If the pixmap does not fit into <n> planes, ppmtoilbm writes a HAM file (if -hamif is used), a 24bit file (if -24if is used) or a direct color file (if -dcif is used) or aborts with an error. -fixplanes | -fp n (min 1, max 16) If a normal ILBM is written, it will have exactly <n> planes. -hambits | -hamplanes n (default 6, min 3, max 16) Select number of planes for HAM picture. The current Amiga hardware supports 6 and 8 planes, so for now you should only use this values. -normal (default) Turns off -hamif/-24if/-dcif, -hamforce/-24force/- dcforce and -cmaponly. -hamif (*) -24if (*) -dcif (*) Write a HAM/24bit/direct color file if the pixmap does not fit into <maxplanes> planes. -hamforce (*) -24force (*) -dcforce (*) Write a HAM/24bit/direct color file. -dcbits | -dcplanes r g b (default 5, min 1, max 16). Select number of bits for red, green & blue in a direct color ILBM. -ecs (default) Shortcut for: -hamplanes 6 -maxplanes 5 -aga Shortcut for: -hamplanes 8 -maxplanes 8 -ham6 Shortcut for: -hamplanes 6 -hamforce -ham8 Shortcut for: -hamplanes 8 -hamforce -map ppmfile Write a normal ILBM using the colors in <ppmfile> as the colormap. The colormap file also determines the number of planes, a -maxplanes or -fixplanes option is ignored. -cmaponly Write a colormap file: only BMHD and CMAP chunks, no BODY chunk, nPlanes = 0. 2 Bugs Needs a real colormap selection algorithm for HAM pictures, instead of using a grayscale colormap. 2 References Amiga ROM Kernel Reference Manual - Devices (3rd Ed.) Addison Wesley, ISBN 0-201-56775-X 2 See_Also ppm(5), ilbmtoppm(1) 2 Authors Copyright (C) 1989 by Jef Poskanzer. Modified August 1993 by Ingo Wilken (Ingo.Wilken@informatik.uni-oldenburg.de) 1 ppmtomitsu ppmtomitsu - convert a portable pixmap to a Mitsubishi S340-10 file 2 Synopsis ppmtomitsu [-sharpness val] [-enlarge val] [-media string] [-copy val] [-dpi300] [-tiny] [ppmfile] 2 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. -sharpness 1-4 'sharpness' designation. Default is to use the current sharpness. -enlarge 1-3 Enlarge by a factor; Default is 1 (no enlarge) -media A, A4, AS, A4S Designate the media you're using. Default is 1184 x 1350, which will fit on any media. A is 1216 x 1350, A4 is 1184 x 1452, AS is 1216 x 1650 and A4S is 1184 x 1754. A warning: If you specify a different media than the printer currently has, the printer will wait until you put in the correct media or switch it off. -copy 1-9 The number of copies to produce. Default is 1. -dpi300 Double the number of allowed pixels for a S3600-30 Printer in S340-10 compatibility mode. (The S3600-30 has 300 dpi). -tiny Memory-safing, but always slow. The printer will get the data line-by-line in 24bit. It's probably a good idea to use this if your machine starts paging a lot without this option. 2 References Mitsubishi Sublimation Full Color Printer S340-10 Specifications of Parallel Interface LSP-F0232F 2 See_Also ppmquant(1), pnmscale(1), ppm(5) 2 Bugs We didn't find any - yet. (Besides, they're called features anyway :-) If you should find one, my email-adress is below. 2 Author Copyright (C) 1992, 93 by S.Petra Zeidler, MPIfR Bonn, Germany. (spz@specklec.mpifr-bonn.mpg.de) 1 ppmtopcx ppmtopcx - convert a portable pixmap into a PCX file 2 Synopsis ppmtopcx [ppmfile] 2 Description Reads a portable pixmap as input. Produces a PCX file as output. 2 See_Also pcxtoppm, ppm 2 Author Copyright (C) 1990 by Michael Davidson. 1 ppmtopgm ppmtopgm - convert a portable pixmap into a portable graymap 2 Synopsis ppmtopgm [ppmfile] 2 Description Reads a portable pixmap as input. Produces a portable gray- map 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. 2 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. 2 See_Also pgmtoppm, ppmtorgb3, rgb3toppm, ppm, pgm 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 ppmtopi1 ppmtopi1 - convert a portable pixmap into an Atari Degas .pi1 file 2 Synopsis ppmtopi1 [ppmfile] 2 Description Reads a portable pixmap as input. Produces an Atari Degas .pi1 file as output. 2 See_Also pi1toppm, ppm, pbmtopi3, pi3topbm 2 Author Copyright (C) 1991 by Steve Belczyk (seb3@gte.com) and Jef Poskanzer. 1 ppmtopict ppmtopict - convert a portable pixmap into a Macintosh PICT file 2 Synopsis ppmtopict [ppmfile] 2 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. 2 Bugs The picture size field is only correct if the output is to a file since writing into this field requires seeking back- wards 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. 2 See_Also picttoppm, ppm, mcvert 2 Author Copyright (C) 1990 by Ken Yap <ken@cs.rocester.edu>. 1 ppmtopj ppmtopj - convert a portable pixmap to an HP PaintJet file 2 Synopsis ppmtopj [-gamma val] [-xpos val] [-ypos val] [-back dark|lite] [-rle] [-center] [-render none|snap|bw|dither|diffuse|monodither|monodiffuse|clusterdither|monoclusterdither] [ppmfile] 2 Description Reads a portable pixmap as input and converts it into a for- mat suitable to be printed by an HP PaintJet printer. 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 send- ing 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 -rle Run length encode the image. (This can result in larger images) -back Enhance the foreground by indicating if the background is light or dark compated to the foreground. -render alg Use an internal rendering algorithm (default dither). -gamma int Gamma correct the image using the integet parameter as a gamma (default 0). -center Center the image to an 8.5 by 11 page -xpos pos Move by pos pixels in the x direction. -ypos pos Move by pos pixels in the y direction. 2 References HP PaintJet XL Color Graphics Printer User's Guide 2 See_Also pnmdepth, ppmquant, ppmdither, ppm 2 Bugs Most of the options have not been tested because of the price of the paper. 2 Author Copyright (C) 1991 by Christos Zoulas. 1 ppmtopuzz ppmtopuzz - convert a portable pixmap into an X11 "puzzle" file 2 Synopsis ppmtopuzz [ppmfile] 2 Description Reads a portable pixmap as input. Produces an X11 "puzzle" file as output. A "puzzle" file is for use with the puzzle program included with the X11 distribution - puzzle's - picture flag lets you specify an image file. 2 See_Also ppm, puzzle 2 Author Copyright (C) 1991 by Jef Poskanzer. 1 ppmtorgb3 ppmtorgb3 - separate a portable pixmap into three portable graymaps 2 Synopsis ppmtorgb3 [ppmfile] 2 Description Reads a portable pixmap as input. Writes three portable graymaps as output, one each for red, green, and blue. The output filenames are constructed by taking the input filename, stripping off any extension, and appending ".red", ".grn", and ".blu". For example, separating lenna.ppm would result in lenna.red, lenna.grn, and lenna.blu. If the input comes from stdin, the names are noname.red, noname.grn, and noname.blu. 2 See_Also rgb3toppm, ppmtopgm, pgmtoppm, ppm, pgm 2 Author Copyright (C) 1991 by Jef Poskanzer. 1 ppmtosixel ppmtosixel - convert a portable pixmap into DEC sixel format 2 Synopsis ppmtosixel [-raw] [-margin] [ppmfile] 2 Description Reads a portable pixmap as input. Produces sixel commands (SIX) as output. The output is formatted for color print- ing, e.g. for a DEC LJ250 color inkjet printer. If RGB values from the PPM file do not have maxval=100, the RGB values are rescaled. A printer control header and a color assignment table begin the SIX file. Image data is written in a compressed format by default. A printer con- trol footer ends the image file. 2 Options -raw If specified, each pixel will be explicitly described in the image file. If -raw is not specified, output will default to compressed format in which identical adjacent pixels are replaced by "repeat pixel" com- mands. A raw file is often an order of magnitude larger than a compressed file and prints much slower. -margin If -margin is not specified, the image will be start at the left margin (of the window, paper, or whatever). If -margin is specified, a 1.5 inch left margin will offset the image. 2 Printing Generally, sixel files must reach the printer unfiltered. Use the lpr -x option or cat filename > /dev/tty0?. 2 Bugs Upon rescaling, truncation of the least significant bits of RGB values may result in poor color conversion. If the ori- ginal PPM maxval was greater than 100, rescaling also reduces the image depth. While the actual RGB values from the ppm file are more or less retained, the color palette of the LJ250 may not match the colors on your screen. This seems to be a printer limitation. 2 See_Also ppm 2 Author Copyright (C) 1991 by Rick Vinci. 1 ppmtotga ppmtotga - convert portable pixmap into a TrueVision Targa file 2 Synopsis ppmtotga [-mono|-cmap|-rgb] [-norle] [ppmfile] 2 Description Reads a portable pixmap as input. Produces a TrueVision Targa file as output. 2 Options -mono Forces Targa file to be of type 8 bit monochrome. Input must be a portable bitmap or a portable graymap. -cmap Forces Targa file to be of type 24 bit colormapped. Input must be a portable bitmap, a portable graymap or a portable pixmap containing no more than 256 distinct colors. -rgb Forces Targa file to be of type 24 bit unmapped color. -norle Disables run-length encoding, in case you have a Targa reader which can't read run-length encoded files. All flags can be abbreviated to their shortest unique pre- fix. If no file type is specified the most highly con- stained compatible type is used, where monochrome is more constained than colormapped which is in turn more constained than unmapped. 2 Bugs Does not support all possible Targa file types. Should really be in PNM, not PPM. 2 See_Also tgatoppm, ppm 2 Author Copyright (C) 1989, 1991 by Mark Shand and Jef Poskanzer. 1 ppmtouil ppmtouil - convert a portable pixmap into a Motif UIL icon file 2 Synopsis ppmtouil [-name uilname] [ppmfile] 2 Description Reads a portable pixmap as input. Produces a Motif UIL icon file as output. If the program was compiled with an rgb database specified, and a RGB value from the ppm input matches a RGB value from the database, then the corresponding color name mnemonic is printed in the UIL's colormap. If no rgb database was com- piled in, or if the RGB values don't match, then the color will be printed with the #RGB, #RRGGBB, #RRRGGGBBB, or #RRRRGGGGBBBB hexadecimal format. 2 Options -name Allows you to specify the prefix string which is printed in the resulting UIL output. If not specified, will default to the filename (without extension) of the ppmfile argument. If -name is not specified and no ppmfile is specified (i.e. piped input), the prefix string will default to the string "noname". All flags can be abbreviated to their shortest unique pre- fix. 2 See_Also ppm 2 Author Converted by Jef Poskanzer from ppmtoxpm.c, which is Copy- right (C) 1990 by Mark W. Snitily 1 ppmtoxpm ppmtoxpm - convert a portable pixmap into an X11 pixmap 2 Synopsis ppmtoxpm [-name xpmname] [ppmfile] 2 Description Reads a portable pixmap as input. Produces X11 pixmap (XPM) as output. If the program was compiled with an rgb database specified, and a RGB value from the ppm input matches a RGB value from the database, then the corresponding color name mnemonic is printed in the XPM's colormap. If no rgb database was com- piled in, or if the RGB values don't match, then the color will be printed with the #RGB, #RRGGBB, #RRRGGGBBB, or #RRRRGGGGBBBB hexadecimal format. 2 Options -name Allows you to specify the prefix string which is printed in the resulting XPM output. If not specified, will default to the filename (without extension) of the ppmfile argument. If -name is not specified and no ppmfile is specified (i.e. piped input), the prefix string will default to the string "noname". All flags can be abbreviated to their shortest unique pre- fix. 2 Example To convert the file "dot" (found in /usr/include/X11/bitmaps), from xbm to xpm one could specify xbmtopbm dot | ppmtoxpm -name dot 2 Bugs An option to match the closest (rather than exact) color name mnemonic from the rgb text would be a desirable enhancement. Truncation of the least significant bits of a RGB value may result in nonexact matches when performing color name mnemonic lookups. 2 See_Also xpmtoppm, ppm 2 Author Copyright (C) 1990 by Mark W. Snitily. 1 ppmtoyuv ppmtoyuv - convert a portable pixmap into an Abekas YUV file 2 Synopsis ppmtoyuv [ppmfile] 2 Description Reads a portable pixmap as input. Produces an Abekas YUV file as output. 2 See_Also yuvtoppm, ppm 2 Author Marc Boucher <marc@PostImage.COM>, based on Example Conver- sion Program, A60/A64 Digital Video Interface Manual, page 69. Copyright (C) 1991 by DHD PostImage Inc. Copyright (C) 1987 by Abekas Video Systems Inc. 1 ppmtoyuvsplit ppmtoyuvsplit - convert a portable pixmap into 3 subsampled raw YUV files 2 Synopsis ppmtoyuvsplit basename [ppmfile] 2 Description Reads a portable pixmap as input. Produces 3 raw files basename.Y, basename.U and basename.V as output. These files are the subsampled raw YUV representation of the input pixmap, as required by the Stanford MPEG codec. The subsam- pling is done by arithmetic mean of 4 pixels colors into one. The YUV values are scaled according to CCIR.601, as assumed by MPEG. 2 See_Also mpeg, ppm 2 Author Copyright (C) 1993 by Andre Beck. (Andreeck@IRS.Inf.TU- Dresden.de) Based on ppmtoyuv.c 1 qrttoppm qrttoppm - convert output from the QRT ray tracer into a portable pixmap 2 Synopsis qrttoppm [qrtfile] 2 Description Reads a QRT file as input. Produces a portable pixmap as output. 2 See_Also ppm 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 rawtoppm rawtoppm - convert raw RGB bytes into a portable pixmap 2 Synopsis rawtoppm [-headerskip N] [-rowskip N] [-rgb|-rbg|-grb |- gbr|-brg|-bgr ] [-interpixel|-interrow] width height [image- data] 2 Description Reads raw RGB bytes as input. Produces a portable pixmap as output. The input file is just RGB bytes. You have to specify the width and height on the command line, since the program obviously can't get them from the file. The maxval is assumed to be 255. If the resulting image is upside down, run it through pnmflip -tb . 2 Options -headerskip If the file has a header, you can use this flag to skip over it. -rowskip If there is padding at the ends of the rows, you can skip it with this flag. -rgb -rbg -grb -gbr -brg -bgr These flags let you specify alternate color orders. The default is -rgb. -interpixel -interrow These flags let you specify how the colors are inter- leaved. The default is -interpixel, meaning inter- leaved by pixel. A byte of red, a byte of green, and a byte of blue, or whatever color order you specified. -interrow means interleaved by row - a row of red, a row of green, a row of blue, assuming standard rgb color order. An -interplane flag - all the red pix- els, then all the green, then all the blue - would be an obvious extension, but is not implemented. You could get the same effect by splitting the file into three parts (perhaps using dd), turning each part into a PGM file with rawtopgm, and then combining them with rgb3toppm. 2 See_Also ppm, rawtopgm, rgb3toppm, pnmflip 2 Author Copyright (C) 1991 by Jef Poskanzer. 1 rgb3toppm rgb3toppm - combine three portable graymaps into one port- able pixmap 2 Synopsis rgb3toppm redpgmfile greenpgmfile bluepgmfile 2 Description Reads three portable graymaps as input. Combines them and produces one portable pixmap as output. 2 See_Also ppmtorgb3, pgmtoppm, ppmtopgm, ppm, pgm 2 Author Copyright (C) 1991 by Jef Poskanzer. 1 sldtoppm sldtoppm - convert an AutoCAD slide file into a portable pixmap 2 Synopsis sldtoppm [-adjust] [-dir] [-height|-ysize s] [-info] [- lib|-Lib name] [-scale s] [-verbose] [-width|-xsize s] [slidefile] 2 Description Reads an AutoCAD(Reg.) slide file and outputs a portable pixmap. If no slidefile is specified, input is read from standard input. The ppmdraw library is used to convert the vector and polygon information in the slide file to a pix- map; see the file ppmdraw.h for details on this package. 2 Options -adjust If the display on which the slide file was created had non-square pixels, when the slide is processed with sldtoppm and the -adjust option is not present, the following warning will appear: Warning - pixels on source screen were non-square. Specifying -adjust will correct image width to com- pensate. Specifying the -adjust option causes sldtoppm to scale the width of the image so that pixels in the resulting portable pixmap are square (and hence circles appear as true circles, not ellipses). The scaling is performed in the vector domain, before scan converting the objects. The results are, therefore, superior in appearance to what you'd obtain were you to perform the equivalent scaling with pnmscale after the bitmap had been created. -dir The input is assumed to be an AutoCAD slide library file. A directory listing each slide in the library is printed on standard error. -height size Scales the image in the vector domain so it is size pixels in height. If no -width or -xsize option is specified, the width will be adjusted to preserve the pixel aspect ratio. -info Dump the slide file header on standard error, display- ing the original screen size and aspect ratio among other information. -lib name Extracts the slide with the given name from the slide library given as input. The specified name is con- verted to upper case. -Lib name Extracts the slide with the given name from the slide library given as input. The name is used exactly as specified; it is not converted to upper case. -scale s Scales the image by factor s, which may be any floating point value greater than zero. Scaling is done after aspect ratio adjustment, if any. Since scaling is per- formed in the vector domain, before rasterisation, the results look much better than running the output of sldtoppm through pnmscale. -verbose Dumps the slide file header and lists every vector and polygon in the file on standard error. -width size Scales the image in the vector domain so it is size pixels wide. If no -height or -ysize option is speci- fied, the height will be adjusted to preserve the pixel aspect ratio. -xsize size Scales the image in the vector domain so it is size pixels wide. If no -height or -ysize option is speci- fied, the height will be adjusted to preserve the pixel aspect ratio. -ysize size Scales the image in the vector domain so it is size pixels in height. If no -width or -xsize option is specified, the width will be adjusted to preserve the pixel aspect ratio. All flags can be abbreviated to their shortest unique pre- fix. 2 Bugs Only Level 2 slides are converted. Level 1 format has been obsolete since the advent of AutoCAD Release 9 in 1987, and was not portable across machine architectures. Slide library items with names containing 8 bit (such as ISO) or 16 bit (Kanji, for example) characters may not be found when chosen with the -lib option unless sldtoppm has been built with character set conversion functions appropri- ate to the locale. You can always retrieve slides from libraries regardless of the character set by using the -Lib option and specifying the precise name of library member. Use the -dir option to list the slides in a library if you're unsure of the exact name. 2 See_Also AutoCAD Reference Manual: Slide File Format, pnmscale, ppm 2 Author John Walker Autodesk SA Avenue des Champs-Montants 14b CH-2074 MARIN Suisse/Schweiz/Svizzera/Svizra/Switzerland Usenet: kelvin@Autodesk.com Fax: 038/33 88 15 Voice: 038/33 76 33 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 restric- tions. This software is provided ``as is'' without express or implied warranty. AutoCAD and Autodesk are registered trademarks of Autodesk, Inc. 1 spctoppm spctoppm - convert an Atari compressed Spectrum file into a portable pixmap 2 Synopsis spctoppm [spcfile] 2 Description Reads an Atari compressed Spectrum file as input. Produces a portable pixmap as output. 2 See_Also sputoppm, ppm 2 Author Copyright (C) 1991 by Steve Belczyk (seb3@gte.com) and Jef Poskanzer. 1 sputoppm sputoppm - convert an Atari uncompressed Spectrum file into a portable pixmap 2 Synopsis sputoppm [spufile] 2 Description Reads an Atari uncompressed Spectrum file as input. Pro- duces a portable pixmap as output. 2 See_Also spctoppm, ppm 2 Author Copyright (C) 1991 by Steve Belczyk (seb3@gte.com) and Jef Poskanzer. 1 tgatoppm tgatoppm - convert TrueVision Targa file into a portable pixmap 2 Synopsis tgatoppm [-debug] [tgafile] 2 Description Reads a TrueVision Targa file as input. Produces a portable pixmap as output. 2 Options -debug Causes the header information to be dumped to stderr. All flags can be abbreviated to their shortest unique pre- fix. Should really be in PNM, not PPM. 2 See_Also ppmtotga, ppm 2 Author Partially based on tga2rast, version 1.0, by Ian J. Mac- Phedran. Copyright (C) 1989 by Jef Poskanzer. 1 ximtoppm ximtoppm - convert an Xim file into a portable pixmap 2 Synopsis ximtoppm [ximfile] 2 Description Reads an Xim file as input. Produces a portable pixmap as output. The Xim toolkit is included in the contrib tree of the X.V11R4 release. 2 See_Also ppm 2 Author Copyright (C) 1991 by Jef Poskanzer. 1 xpmtoppm xpmtoppm - convert an X11 pixmap into a portable pixmap 2 Synopsis xpmtoppm [xpmfile] 2 Description Reads an X11 pixmap (XPM) as input. Produces a portable pixmap as output. 2 See_Also ppmtoxpm, ppm 2 Author Copyright (C) 1991 by Jef Poskanzer. 1 yuvtoppm yuvtoppm - convert Abekas YUV bytes into a portable pixmap 2 Synopsis yuvtoppm width height [imagedata] 2 Description Reads raw Abekas YUV bytes as input. Produces a portable pixmap as output. The input file is just YUV bytes. You have to specify the width and height on the command line, since the program obviously can't get them from the file. The maxval is assumed to be 255. 2 See_Also ppmtoyuv, ppm 2 Author Marc Boucher <marc@PostImage.COM>, based on Example Conver- sion Program, A60/A64 Digital Video Interface Manual, page 69. Copyright (C) 1991 by DHD PostImage Inc. Copyright (C) 1987 by Abekas Video Systems Inc. 1 yuvsplittoppm yuvplittoppm - convert a Y- an U- and a V-file into a port- able pixmap. 2 Synopsis yuvsplittoppm basename width height [-ccir601] 2 Description Reads three files, containing the YUV components, as input. These files are basename .Y, basename.U and basename.V . Produces a portable pixmap on stdout. Since the YUV files are raw files, the dimensions width and height must be specified on the command line. 2 Options -ccir601 Assumes that the YUV triplets are scaled into the smaller range of the CCIR 601 (MPEG) standard. Else, the JFIF (JPEG) standard is assumed. 2 See_Also ppmtoyuvsplit, yuvtoppm, ppm 2 Author Marcel Wijkstra <wijkstra@fwi.uva.nl>, based on ppmtoyuvsplit. 1 ppmforge ppmforge - fractal forgeries of clouds, planets, and starry skies 2 Synopsis ppmforge [-clouds] [-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] 2 Description ppmforge generates three kinds of ``random fractal for- geries,'' the term coined by Richard F. Voss of the IBM Tho- mas J. Watson Research Center for seemingly realistic pic- tures of natural objects generated by simple algorithms em- bodying randomness and fractal self-similarity. The tech- niques 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 generat- ed 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 prepara- tion 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 in- creases as the square of the mesh size. The fractal dimen- sion, 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 ampli- tudes. 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 op- tion. 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: Clouds A colour map is created that ranges from pure blue to white by increasing admixture (desaturation) of blue with white. Numbers less than 0.5 are coloured blue, numbers between 0.5 and 1.0 are coloured with corresponding levels of white, with 1.0 being pure white. Planet The mesh is projected onto a sphere. Values less than 0.5 are treated as water and values between 0.5 and 1.0 as land. The water areas are coloured based upon the water depth, and land based on its elevation. The random depth data are used to create clouds over the oceans. An atmosphere ap- proximately like the Earth's is simulated; its light absorption is calculated to create a blue cast around the limb of the planet. A function that rises from 0 to 1 based on latitude is modu- lated by the local elevation to generate polar ice caps--high altitude terrain carries glaciers farther from the pole. Based on the position of the star with respect to the observer, the ap- parent colour of each pixel of the planet is cal- culated by ray-tracing from the star to the planet to the observer and applying a lighting model that sums ambient light and diffuse reflection (for most planets ambient light is zero, as their pri- mary star is the only source of illumination). Additional random data are used to generate stars around the planet. Night A sequence of pseudorandom numbers is used to gen- erate stars with a user specified density. 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 pro- duces better looking planets. ppmquant tends to create discrete colour bands, particularly in the oceans, which are unrealistic and distracting. The number of colours in star- ry 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. 2 Options -clouds Generate clouds. A pixmap of fractal clouds is generated. Selecting clouds sets the default for fractal dimension to 2.15 and power scale factor to 0.75. -dimension dimen Sets the fractal dimension to the specified dimen, which may be any floating point value between 0 and 3. Higher fractal dimensions create more ``chaotic'' images, which require higher resolu- tion output and a larger FFT mesh size to look good. If no dimension is specified, 2.4 is used when generating planets and 2.15 for clouds. -glaciers level The floating point level setting controls the ex- tent to which terrain elevation causes ice to ap- pear at lower latitudes. The default value of 0.75 makes the polar caps extend toward the equa- tor across high terrain and forms glaciers in the highest mountains, as on Earth. Higher values make ice sheets that cover more and more of the land surface, simulating planets in the midst of an ice age. Lower values tend to be boring, resulting in unrealistic geometrically-precise ice cap boundaries. -hour hour When generating a planet, hour is used as the ``hour angle at the central meridian.'' If you specify -hour 12, for example, the planet will be fully illuminated, corresponding to high noon at the longitude at the centre of the screen. You can specify any floating point value between 0 and 24 for hour, but values which place most of the planet in darkness (0 to 4 and 20 to 24) result in crescents which, while pretty, don't give you many illuminated pixels for the amount of computing that's required. If no -hour option is specified, a random hour angle is chosen, biased so that only 25% of the images generated will be crescents. -ice level Sets the extent of the polar ice caps to the given floating point level. The default level of 0.4 produces ice caps similar to those of the Earth. Smaller values reduce the amount of ice, while larger -ice settings create more prominent ice caps. Sufficiently large values, such as 100 or more, in conjunction with small settings for - glaciers (try 0.1) create ``ice balls'' like Euro- pa. -inclination|-tilt angle The inclination angle of the planet with regard to its primary star is set to angle, which can be any floating point value from -90 to 90. The inclina- tion angle can be thought of as specifying, in de- grees, the ``season'' the planet is presently ex- periencing or, more precisely, the latitude at which the star transits the zenith at local noon. If 0, the planet is at equinox; the star is directly overhead at the equator. Positive values represent summer in the northern hemisphere, nega- tive values summer in the southern hemisphere. The Earth's inclination angle, for example, is about 23.5 at the June solstice, 0 at the equinoxes in March and September, and -23.5 at the December solstice. If no inclination angle is specified, a random value between -21.6 and 21.6 degrees is chosen. -mesh size A mesh of size by size will be used for the fast Fourier transform (FFT). Note that memory re- quirements and computation speed increase as the square of size; if you double the mesh size, the program will use four times the memory and run four times as long. The default mesh is 256x256, which produces reasonably good looking pictures while using half a megabyte for the 256x256 array of single precision complex numbers required by the FFT. On machines with limited memory capaci- ty, you may have to reduce the mesh size to avoid running out of RAM. Increasing the mesh size pro- duces better looking pictures; the difference be- comes particularly noticeable when generating high resolution images with relatively high fractal di- mensions (between 2.2 and 3). -night A starry sky is generated. The stars are created by the same algorithm used for the stars that sur- round planet pictures, but the output consists ex- clusively of stars. -power factor Sets the ``power factor'' used to scale elevations synthesised from the FFT to factor, which can be any floating point number greater than zero. If no factor is specified a default of 1.2 is used if a planet is being generated, or 0.75 if clouds are selected by the -clouds option. The result of the FFT image synthesis is an array of elevation values between 0 and 1. A non-unity power factor exponentiates each of these elevations to the specified power. For example, a power factor of 2 squares each value, while a power factor of 0.5 replaces each with its square root. (Note that exponentiating values between 0 and 1 yields values that remain within that range.) Power fac- tors less than 1 emphasise large-scale elevation changes at the expense of small variations. Power factors greater than 1 increase the roughness of the terrain and, like high fractal dimensions, may require a larger FFT mesh size and/or higher screen resolution to look good. -saturation sat Controls the degree of colour saturation of the stars that surround planet pictures and fill star- ry skies created with the -night option. The de- fault value of 125 creates stars which resemble the sky as seen by the human eye from Earth's sur- face. Stars are dim; only the brightest activate the cones in the human retina, causing colour to be perceived. Higher values of sat approximate the appearance of stars from Earth orbit, where better dark adaptation, absence of skyglow, and the concentration of light from a given star onto a smaller area of the retina thanks to the lack of atmospheric turbulence enhances the perception of colour. Values greater than 250 create ``science fiction'' skies that, while pretty, don't occur in this universe. Thanks to the inverse square law combined with Nature's love of mediocrity, there are many, many dim stars for every bright one. This population relationship is accurately reflected in the skies created by ppmforge. Dim, low mass stars live much longer than bright massive stars, consequent- ly there are many reddish stars for every blue gi- ant. This relationship is preserved by ppmforge. You can reverse the proportion, simulating the sky as seen in a starburst galaxy, by specifying a negative sat value. -seed num Sets the seed for the random number generator to the integer num. The seed used to create each picture is displayed on standard output (unless suppressed with the -quiet option). Pictures gen- erated with the same seed will be identical. If no -seed is specified, a random seed derived from the date and time will be chosen. Specifying an explicit seed allows you to re-render a picture you particularly like at a higher resolution or with different viewing parameters. -stars fraction Specifies the percentage of pixels, in tenths of a percent, which will appear as stars, either sur- rounding a planet or filling the entire frame if -night is specified. The default fraction is 100. -xsize|-width width Sets the width of the generated image to width pixels. The default width is 256 pixels. Images must be at least as wide as they are high; if a width less than the height is specified, it will be increased to equal the height. If you must have a long skinny pixmap, make a square one with ppmforge, then use pnmcut to extract a portion of the shape and size you require. -ysize|-height height Sets the height of the generated image to height pixels. The default height is 256 pixels. If the height specified exceeds the width, the width will be increased to equal the height. All flags can be abbreviated to their shortest unique pre- fix. 2 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. 2 See_Also pnmcut, pnmdepth, ppmdither, ppmquant, ppm [1] Voss, Richard F., ``Random Fractal Forgeries,'' in Earnshaw et. al., Fundamental Algorithms for Computer Graphics, Berlin: Springer-Verlag, 1985. [2] Peitgen, H.-O., and Saupe, D. eds., The Science Of Fractal Images, New York: Springer Verlag, 1988. 2 Author John Walker Autodesk SA Avenue des Champs-Montants 14b CH-2074 MARIN Suisse/Schweiz/Svizzera/Svizra/Switzerland Usenet: kelvin@Autodesk.com Fax: 038/33 88 15 Voice: 038/33 76 33 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 restric- tions. 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 introduc- tion by James Gleick and detailed explanations by Rudy Ruck- er of the mathematics and algorithms used by each program. 1 ppmpat ppmpat - make a pretty pixmap 2 Synopsis ppmpat -gingham2|-g2|-gingham3| -g3|-madras|-tartan| - poles|-squig|-camo| -anticamo width height 2 Description Produces a portable pixmap of the specified width and height, with a pattern in it. 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 rou- tines. 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 back- ground. 2 Options The different flags specify various different pattern types: -gingham2 A gingham check pattern. Can be tiled. -gingham3 A slightly more complicated gingham. Can be tiled. -madras A madras plaid. Can be tiled. -tartan A tartan plaid. Can be tiled. -poles Color gradients centered on randomly-placed poles. May need to be run through ppmquant. -squig Squiggley tubular pattern. Can be tiled. May need to be run through ppmquant. -camo Camouflage pattern. May need to be run through ppmquant. -anticamo Anti-camouflage pattern - like -camo, but ultra-bright colors. May need to be run through ppmquant. All flags can be abbreviated to their shortest unique pre- fix. 2 References Some of the patterns are from "Designer's Guide to Color 3" by Jeanne Allen. 2 See_Also pnmtile, ppmquant, ppm 2 Author Copyright (C) 1989 by Jef Poskanzer. 1 ppmqvga ppmqvga - 8 plane quantization 2 Synopsis ppmqvga [ options ] [ input file ] 2 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. 2 Options -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 map- ping. May be repeated to generate loads of internal table output, but generally only useful once. 2 Examples ppmqvga -d mymage.ppm | ppmtogif >mymage.gif tgatoppm zombie.tga | ppmqvga | ppmtotif > zombie.tif 2 See_Also ppmquant 2 Diagnostics Error messages if problems, various levels of optional pro- gress reporting. 2 Limitations none known. 2 Author Original by Lyle Rains (lrains@netcom.com) as ppmq256 and ppmq256fs combined, documented, and enhanced by Bill David- sen (davidsen@crd.ge.com) 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. 1 ppmtomap ppmtomap - extract all colors from a portable pixmap 2 Synopsis ppmtomap [-sort] [-square] [ppmfile] 2 Description Reads a portable pixmap as input. Produces a portable pix- map as output, representing a color map of the input file. All N different colors found are put in an Nx1 portable pix- map. This color map file can be used as a mapfile for ppmquant or ppmtogif. 2 Options -sort Produces a portable pixmap with the colors in some sorted order. -square Produces a (more or less) square output file, instead of putting all colors on the top row. All flags can be abbreviated to their shortest unique pre- fix. 2 WARNING If you want to use the output file as a mapfile for ppmto- gif, you first have to do a ppmquant 256, since ppmtomap is not limited to 256 colors (but to 65536). 2 See_Also ppmtogif, ppmquant, ppm 2 Author Marcel Wijkstra (wijkstra@fwi.uva.nl). Copyright (C) 1989 by Jef Poskanzer. 1 ppmtopjxl ppmtopjxl - convert a portable pixmap into an HP PaintJet XL PCL file 2 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] 2 Description Reads a portable pixmap as input. Produces a PCL file suit- able 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 presen- tation 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 inter- preted as the number of dots to set the width or height to, but an optional dimension of `pt' (points), `dp' (deci- points), `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. 2 See_Also ppm 2 Author Angus Duggan 1 libppm libppm - functions to support portable pixmap programs 2 Synopsis #include <ppm.h> cc ... libppm.a libpgm.a libpbm.a 2 Description TYPES AND CONSTANTS typedef ... pixel; typedef ... pixval; #define PPM_MAXMAXVAL ... extern pixval ppm_pbmmaxval; Each pixel contains three pixvals, each of which should con- tain 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 ) For distinguishing different file formats and types. pixval PPM_GETR( pixel p ) pixval PPM_GETG( pixel p ) pixval PPM_GETB( pixel p ) These three macros retrieve the red, green or blue value from the given pixel. void PPM_ASSIGN( pixel p, pixval red, pixval grn, pixval blu ) This macro assigns the given red, green and blue values to the pixel. int PPM_EQUAL( pixel p, pixel q ) This macro checks two pixels for equality. void PPM_DEPTH( pixel newp, pixel p, pixval oldmaxval, pixval newmaxval ) 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. float PPM_LUMIN( pixel p ) This macro determines the luminance of the pixel p. MEMORY MANAGEMENT pixel** ppm_allocarray( int cols, int rows ) Allocate an array of pixels. pixel* ppm_allocrow( int cols ) Allocate a row of the given number of pixels. void ppm_freearray( pixel** pixels, int rows ) Free the array allocated with ppm_allocarray() containing the given number of rows. void pbm_freerow( pixel* pixelrow ) Free a row of pixels. READING PBM FILES 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(). pixel** ppm_readppm( FILE* fp, int* colsP, int* rowsP, pixval* maxvalP ) Read an entire pixmap file into memory, returning the allo- cated array and filling in the rows, cols and maxval vari- ables. This function combines ppm_readppminit(), ppm_allocarray() and ppm_readppmrow(). WRITING FILES 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 ) Write a row from a portable pixmap. 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(). COLOR NAMES pixel ppm_parsecolor( char* colorname, pixval maxval ) 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. char* ppm_colorname( pixel* colorP, pixval maxval, int hexok ) 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. 2 See_Also pbm, pgm 2 Author Copyright (C) 1989, 1991 by Tony Hansen and Jef Poskanzer. 1 ppm ppm - portable pixmap file format 2 Description The portable pixmap format is a lowest common denominator color image file format. The definition is as follows: - A "magic number" for identifying the file type. A ppm file's magic number is the two characters "P3". - Whitespace (blanks, TABs, CRs, LFs). - A width, formatted as ASCII characters in decimal. - Whitespace. - A height, again in ASCII decimal. - Whitespace. - The maximum color-component value, again in ASCII decimal. - Whitespace. - Width * height pixels, each three ASCII decimal values between 0 and the specified maximum value, starting at the top-left corner of the pixmap, proceeding in normal English reading order. The three values for each pixel represent red, green, and blue, respectively; a value of 0 means that color is off, and the maximum value means that color is maxxed out. - Characters from a "#" to the next end-of-line are ignored (comments). - No line should be longer than 70 characters. 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 pos- sible, 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: - The "magic number" is "P6" instead of "P3". - The pixel values are stored as plain bytes, instead of ASCII decimal. - Whitespace is not allowed in the pixels area, and only a single character of whitespace (typically a newline) is allowed after the maxval. - The files are smaller and many times faster to read and write. 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. 2 See_Also giftopnm, gouldtoppm, ilbmtoppm, imgtoppm, mtvtoppm, pcxtoppm, pgmtoppm, pi1toppm, picttoppm, pjtoppm, qrttoppm, rawtoppm, rgb3toppm, sldtoppm, spctoppm, sputoppm, tgatoppm, ximtoppm, xpmtoppm, yuvtoppm, ppmtoacad, ppmtogif, ppmtoicr, ppmtoilbm, ppmtopcx, ppmtopgm, ppmtopi1, ppmtopict, ppmtopj, ppmtopuzz, ppmtorgb3, ppmtosixel, ppmtotga, ppmtouil, ppmtoxpm, ppmtoyuv, ppmdither, ppmforge, ppmhist, ppmmake, ppmpat, ppmquant, ppmquantall, ppmrelief, pnm, pgm, pbm 2 Author Copyright (C) 1989, 1991 by Jef Poskanzer. 1 pgmkernel pgmkernel - generate a convolution kernel 2 Synopis pgmkernel [-weight w] width [height] 2 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. 2 Options The optional -weight flag should be a real number greater than -1. The default value is 6.0. 2 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. 2 See_Also pnmconvol(1), pnmsmooth(1) 2 Author Alberto Accomazzi (alberto@cfa.harvard.edu). 1 fitstopnm fitstopnm - convert a FITS file into a portable anymap 2 Synopis fitstopnm [-image N] [-noraw] [-scanmax] [-printmax] [-min f] [-max f] [FITSfile] 2 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. 2 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. 2 References FITS stands for Flexible Image Transport System. A full description can be found in Astronomy & Astrophysics Supplement Series 44 (1981), page 363. 2 See_Also pnmtofits(1), pgm(5), pnmflip(1) 2 Author Copyright (C) 1989 by Jef Poskanzer, with modifications by Daniel Briggs (dbriggs@nrao.edu) and Alberto Accomazzi (alberto@cfa.harvard.edu). 1 pnmalias pnmalias - antialias a portable anyumap. 2 Synopis pnmalias [-bgcolor color] [-fgcolor color] [-bonly] [-fonly] [-balias] [-falias] [-weight w] [pnmfile] 2 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. 2 Options -bgcolor colorb, -fgcolor colorf set 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: o A name, assuming that a pointer to an X11-style color names file was compiled in. o An X11-style hexadecimal specifier: rgb:r/g/b, where r g and b are each 1- to 4-digit hexadecimal numbers. o An X11-style decimal specifier: rgbi:r/g/b, where r g and b are floating point numbers between 0 and 1. o For backwards compatibility, an old-X11-style hexadecimal number: #rgb, #rrggbb, #rrrgggbbb, or #rrrrggggbbbb. o For backwards compatibility, a triplet of numbers separated by commas: r,g,b, where r g and b are floating point numbers between 0 and 1. (This style was added before MIT came up with the similar rgbi style.) 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. -bonly, -fonly Apply anti-aliasing only to background (-bonly), or foreground (-fonly) pixels. -balias, -falias Apply 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. -weight w Use 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. 2 See_Also pbmtext(1), pnmsmooth(1), pnm(5) 2 Author Copyright (C) 1992 by Alberto Accomazzi, Smithsonian Astrophysical Observatory. 1 pnmtofits pnmtofits - convert a portable anymap into FITS format 2 Synopis pnmtofits [-max f] [-min f] [pnmfile] 2 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. 2 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. 2 See_Also fitstopnm(1), pgm(5) 2 Author Copyright (C) 1989 by Wilson H. Bent (whb@hoh-2.att.com), with modifications by Alberto Accomazzi (alberto@cfa.harvard.edu). 1 ppmchange ppmchange - change all pixels of one color to another in a portable pixmap 2 Synopis ppmchange oldcolor newcolor [...] [ppmfile] 2 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: o A name, assuming that a pointer to an X11-style color names file was compiled in. o An X11-style hexadecimal specifier: rgb:r/g/b, where r g and b are each 1- to 4-digit hexadecimal numbers. o An X11-style decimal specifier: rgbi:r/g/b, where r g and b are floating point numbers between 0 and 1. o For backwards compatibility, an old-X11-style hexadecimal number: #rgb, #rrggbb, #rrrgggbbb, or #rrrrggggbbbb. o For backwards compatibility, a triplet of numbers separated by commas: r,g,b, where r g and b are floating point numbers between 0 and 1. (This style was added before MIT came up with the similar rgbi style.) 2 See_Also pgmtoppm(1), ppm(5) 2 Author Wilson H. Bent. Jr. (whb@usc.edu) with modifications by Alberto Accomazzi (alberto@cfa.harvard.edu) 1 xvminitoppm xvminitoppm - convert a XV "thumbnail" picture to PPM 2 Synopis xvminitoppm [xvminipic] 2 Description Reads a XV "thumbnail" picture (a miniature picture generated by the "VisualSchnauzer" browser) as input. Produces a portable pixmap as output. 2 See_Also ppm(5), xv(1) 2 Author Copyright (C) 1993 by Ingo Wilken