Converters pnmtopnm convert PNM image to PNM raw or plain pgmtopgm convert PGM or PBM image to PGM ppmtoppm convert PPM, PGM, or PBM image to PPM pbmtopgm convert PBM image to PGM by averaging areas pgmtopbm (Obsolete) convert PGM image to PBM by dithering pgmtoppm colorize a PGM into a PPM ppmtopgm convert PPM image to PGM ppmtompeg convert series of PPM frames to an MPEG movie jpegtopnm convert JFIF/JPEG/EXIF file to Netpbm format pnmtojpeg convert PNM to JPEG/JFIF/EXIF format pamtojpeg2k convert PNM/PAM to JPEG-2000 code stream jpeg2ktopam convert JPEG-2000 code stream to PAM/PNM anytopnm convert any graphics format to Netpbm format bmptopnm convert Windows or OS/2 Bitmap file to PPM or PGM ppmtobmp convert PPM to Windows or OS/2 Bitmap file winicontoppm convert Windows icon file to PPM ppmtowinicon convert PPM to Windows icon file giftopnm convert GIF to PNM ppmtogif convert PPM to GIF pnmtopng convert Netpbm format to Portable Network Graphics pngtopnm convert PNG (Portable Network Graphics) to Netpbm formats palmtopnm convert Palm pixmap to Netpbm formats pnmtopalm convert Netpbm formats to Palm pixmap ddbugtopbm convert Palm DiddleBug image to PBM jbigtopnm convert JBIG BIE (compressed bitmap) to PNM pamtopnm convert a PAM image to PBM, PGM, or PPM pnmtojbig convert PNM to JBIG BIE (compressed bitmap) pnmtofiasco convert Netpbm image to Fiasco (wfa) highly compressed format fiascotopnm convert Fiasco (wfa) highly compressed format to Netpbm image pamtopfm convert PAM/PNM to HDRshop PFM (Portable Float Map) pfmtopam convert HDRshop PFM (Portable Float Map) to PAM pbmtomrf convert PBM image to MRF (compressed bitmap) mrftopbm convert MRF (compressed bitmap) to PBM hpcdtoppm convert photo CD to PPM pcdovtoppm Convert a photo CD PCD overview file to PPM pbmtonokia convert PBM to Nokia Smart Messaging Format (SMF) pbmtowbmp convert PBM to WAP (Wireless App Protocol) Wireless Bitmap wbmptopbm convert WAP (Wireless App Protocol) Wireless Bitmap to PBM pamtohtmltbl convert PNM/PAM to an HTML table with a colored cell for each pixel pbmtomda convert from PBM to Microdesign (for Amstrad PCWs) mdatopbm convert from Microdesign (for Amstrad PCWs) to PBM atktopbm convert Andrew Toolkit raster object to PBM pbmtoatk convert PBM to Andrew Toolkit raster object brushtopbm convert Xerox doodle brushes to PBM cmuwmtopbm convert CMU window manager format to PBM g3topbm convert Group 3 FAX to PBM pbmtog3 convert PBM to Group 3 FAX icontopbm convert Sun icon to PBM pbmtoicon convert PBM to Sun icon gemtopnm convert GEM .img format to PBM or pixmap macptopbm convert MacPaint to PBM pbmtomacp convert PBM to MacPaint mgrtopbm convert MGR format to PBM pbmtomgr convert PBM to MGR format infotopam convert Amiga .info icons to PAM neotoppm convert Atari Neochrome (.neo) image to PPM ppmtoneo convert PPM image to Atari Neochrome (.neo) pi1toppm convert Atari Degas .pi1 to PPM ppmtopi1 convert PPM to Atari Degas .pi1 pc1toppm convert Atari Degas .pc1 (compressed pi1) to PPM pi3topbm convert Atari Degas .pi3 to PBM pbmtopi3 convert PBM to Atari Degas .pi3 xbmtopbm convert X10 or X11 bitmap to PBM pbmtoxbm convert PBM to X11 bitmap pbmtox10bm convert PBM to X10 bitmap ybmtopbm convert Bennet Yee "face" file into PBM pbmtoybm convert PBM into Bennet Yee "face" file pbmtoepson convert PBM to Epson 9-pin printer graphics pbmtoescp2 convert PBM to Epson ESC/P2 printer graphics escp2topbm convert Epson ESC/P2 printer graphics to PBM pbmto10x convert PBM to Gemini 10x printer graphics pnmtopclxl convert PNM to HP PCL-XL (PCL 6) printer language ppmtopjxl convert from PPM to HP Paintjet XL PCL printer stream pbmtolj convert PBM to HP LaserJet black and white graphics ppmtolj convert PPM to HP LaserJet color graphics (PCL 5) pjtoppm convert HP PaintJet file to PPM ppmtopj convert PPM to HP PaintJet file thinkjettopbm convert HP Thinkjet printer stream to PBM pbmtoppa convert PBM to HP PPA (Printer Performance Architecture) printer stream ppmtomitsu convert from PPM to Mitsubishi S340-10 printer stream pbmtoibm23xx convert from PBM to IBM 23XX printer stream ppmtoterm Display PPM image on ANSI standard text terminal pbmto4425 Display PBM image on AT&T 4425 ASCII terminal with gfx chars pbmtoascii convert PBM to ASCII graphic form asciitopgm convert ASCII character graphics to PGM pbmtobbnbg convert PBM to BBN BitGraph graphics pbmtocmuwm convert PBM to CMU window manager format pbmtogem convert PBM into GEM .img file pbmtogo convert PBM to GraphOn graphics pbmtoplot convert PBM into Unix plot file pbmtoptx convert PBM to Printronix graphics pbmtozinc convert PBM to Zinc Interface Library icon fitstopnm convert FITS format to PNM pnmtofits convert Netpbm formats to FITS format fstopgm convert Usenix FaceSaver(tm) format to PGM pgmtofs convert PGM to Usenix FaceSaver(tm) format hipstopgm convert HIPS format to PGM lispmtopgm convert a Lisp Machine bitmap file into PGM format pgmtolispm convert PGM into Lisp Machine format pnmtops convert Netpbm formats to Postscript pstopnm convert Postscript to Netpbm formats psidtopgm convert PostScript "image" data to PGM pbmtolps convert PBM image to Postscript using lines pbmtoepsi convert a PBM image to encapsulated Postscript preview bitmap pbmtopsg3 convert PBM images to Postscript using G3 fax compression. rawtopgm convert raw grayscale bytes to PGM gouldtoppm convert Gould scanner file to PPM ilbmtoppm convert IFF ILBM to PPM ppmtoilbm convert PPM to IFF ILBM imgtoppm convert Img-whatnot to PPM mtvtoppm convert MTV ray-tracer output to PPM pcxtoppm convert PC Paintbrush format to PPM picttoppm convert Macintosh PICT to PPM ppmtopict convert PPM to Macintosh PICT qrttoppm convert QRT ray-tracer output to PPM rawtoppm convert raw RGB bytes to PPM sldtoppm convert an AutoCAD slide file into a PPM spctoppm convert Atari compressed Spectrum to PPM sputoppm convert Atari uncompressed Spectrum to PPM tgatoppm convert TrueVision Targa file to PPM pamtotga convert PAM to TrueVision Targa file ximtoppm convert Xim to PPM xpmtoppm convert XPM format to PPM ppmtoxpm convert PPM to XPM format yuvtoppm convert Abekas YUV format to PPM eyuvtoppm convert Encoder/Berkeley YUV format to PPM ppmtoeyuv convert PPM to Encoder/Berkeley YUV format ppmtoyuv convert PPM to Abekas YUV format ppmtoyuvsplit convert PPM to 3 subsampled raw Stanford MPEG YUV files yuvsplittoppm merge 3 subsampled raw YUV files to one PPM ppmtoacad convert PPM to AutoCAD database or slide ppmtoicr convert PPM to NCSA ICR graphics ppmtopcx convert PPM to PC Paintbrush format ppmtopuzz convert PPM to X11 "puzzle" file rasttopnm convert Sun raster file to Netpbm formats pnmtorast convert Netpbm formats to Sun raster file tifftopnm convert TIFF file to PNM pnmtotiff convert Netpbm formats to TIFF RGB file pnmtotiffcmyk convert Netpbm formats to TIFF CMYK file xwdtopnm convert X10 or X11 window dump to Netpbm formats pnmtoxwd convert Netpbm formats to X11 window dump 411toppm convert 411 (Sony Mavica) to PPM ppmtosixel convert PPM to DEC sixel format ppmtouil convert PPM to Motif UIL icon file sbigtopgm convert Santa Barbara Instrument Group CCD file to PGM vidtoppm convert Parallax XVideo JPEG to sequence of PPM files pnmtorle convert PNM to Utah Raster Toolkit (urt/rle) file rletopnm convert Utah Raster Toolkit (urt/rle) file to PNM pamtodjvurle convert PNM/PAM to DjVu Color RLE format pbmtodjvurle convert PBM to DjVu Bitonal RLE format ppmtoleaf convert PPM to Interleaf leaftoppm convert Interleaf to PPM bioradtopgm convert Biorad confocal image to PGM pbmtoln03 convert PGM image to Dec LN03+ Sixel image pbmtopk convert PBM image to packed format (PK) font pktopbm convert packed format (PK) font to PBM image pamtohdiff convert PAM image to horizontal difference version of same hdifftopam convert horizontal difference PAM back to original image pnmtoddif convert from Netpbm formats to DDIF pnmtosgi convert from Netpbm formats to SGI format sgitopnm convert from SGI format to Netpbm formats pnmtosir convert from Netpbm formats to Solitaire Image Recorder file (MGI Type 11 or 17) sirtopnm convert from Solitaire Image Recorder file to Netpbm formats. spottopgm convert SPOT satellite image to PGM xvminitoppm convert Xv "thumbnail" picture to PPM zeisstopnm convert a Zeiss confocal file to Netpbm format ppmtoarbtxt.html convert PPM to just about any text-based format, using a grammar file Image Generators All of these generate Netpbm format output. pbmmake create a blank PBM image of a specified size ppmmake create a PPM image of a specified size and color pgmramp generate a grayscale ramp ppmpat create a pretty PPM image ppmrainbow create a spectrum-like image with colors fading together. ppmrough create PPM image of two colors with a ragged border between them pgmnoise create a PGM image of white noise pbmtext render text into a PBM image pbmtextps render text into a PBM image using a Postscript interpreter pbmupc create a Universal Product Code PBM image pamstereogram create a single image stereogram from a height map ppmwheel generate a hue-value color wheel ppmcie generate a CIE color map PPM image pbmpage create a printer test pattern page in PBM format pamseq create a PAM image of all possible tuple values. E.g. a color map containing all possible colors of given maxval pamgauss create a PAM image of a Gaussian (bell curve; normal curve) function. Image Editors All of these work on the Netpbm formats ppmlabel Add text to an image ppmshadow add a shadow to an image so it looks like it's floating ppmbrighten brighten or dim an image -- change saturation and value ppmflash brighten an image ppmdim dim an image - different way from ppmbrighten ppmfade Produce series of images fading from one to another pbmreduce reduce a PBM N times, using Floyd-Steinberg pnmnorm normalize contrast pbmpscale enlarge a PBM image with edge smoothing pamscale scale/resample an image with high precision pnmscale scale an image with high precision - obsolete pnmscalefixed scale an image quickly with low precision pnmenlarge enlarge an image N times pamperspective Change perspective distortion in an image ppmdither ordered dither for color images pamditherbw dither a grayscale image to black and white (convert PGM to PBM) pnmcolormap Choose the N best colors to represent an image; create a colormap pnmremap Replace colors in an image with those from a color map ppmquant quantize colors in a color image down to fewer colors - obsolete pnmquant quantize colors/shades in a color or grayscale image down to fewer ppmquantall quantize colors on many files ppmrelief run a Laplacian Relief filter on a PPM pamfunc apply simple arithmetic function to samples in an image pamarith apply simple arithmetic binary function to samples in two images pamsummcol summarize (sum, average, etc) an image by column pnmcat concatenate images pnmpad add borders to an image pamcomp create composite (overlay) of images pnmcomp obsolete version of pamcomp (kept because it may have fewer bugs) ppmmix mix (overlay) two images. pnmcrop crop all like-colored borders off an image pamcut select a rectangular region from an image pnmcut obsolete version of pamcut (kept because it may have fewer bugs) pamdice slice an image into many horizontally and/or vertically pamdeinterlace remove every other row from an image pnmstitch stitch together panoramic (side-by-side) photographs ppmglobe Turn a cylindrical projection into strips that can be glued onto a sphere pamchannel extract individual planes (channel, e.g. R, G, or B) from an image pamstack stack the planes of multiple PAM images into a single output image pamlookup map an image to a new image by using it as indices into a table pnmdepth change the maxval in an image pamendian Swap bytes in multi-byte samples of a PAM image pamflip perform one or more flip operations on an image pamstretch scale up an image by inserting interpolated pixels pamstretch-gen scale by non-integer values using pamstretch and pamscale pnminvert invert an image pnmgamma perform gamma correction on an image pnmhisteq histogram equalize image to increase contrast pnmmargin add a margin to an image pnmpaste paste a rectangle into an image pnmrotate rotate an image pnmshear shear an image pgmabel create cross-section of an image using Abel integration for deconvolution pnmsmooth smooth an image pnmtile replicate an image into a specified size pbmclean remove lone pixels (snow) from a PBM image pnmalias antialias an image ppmchange change all of one color to another in PPM image pnmnlfilt filter an image by replacing each pixel with a function of nearby pixels ppmshift shift lines of PPM image left or right a random amount ppmspread move pixels of PPM image a random amount pnmconvol general MxN convolution on an image. Can blur an image. pgmmorphconv utions on a PGM image: dilation and erosion. pgmminkowski Compute Minkowski integral over a PGM image pamedge edge-detect (outline) an image pammasksharpen sharpen an image via an unsharp mask rgb3toppm combine three PGMs into one PPM ppmtorgb3 separate a PPM into three PGMs pgmenhance edge-enhance a PGM image pbmlife apply Conway's rules of Life to a PBM image ppmdist map colors to high contrast grayscales arbitrarily ppmntsc adjust colors so they are legal for NTSC or PAL television Image Analyzers These all work on the Netpbm formats as input. pamfile describe an image's vital characteristics pnmpsnr measure difference between two images pamslice print a row or column of an image in ASCII decimal pgmtexture calculate textural features on a PGM image pgmhist print a histogram of the values in a PGM image ppmhist print a histogram of a PPM pnmhistmap draw a histogram of a PGM or PPM pnmcolormap create quantization color map for an image pamsumm Summarize (sum, average, etc.) all samples in an image pamsharpness measure the sharpness of an image pamsharpmap create map of sharpness in an image ppm3d generate a blue/green 3D glasses image from two images Miscellaneous ppmsvgalib display a PPM image on a Linux virtual console using Svgalib pbmmask create a mask bitmap from a regular bitmap ppmcolormask create mask of areas of a certain color in an image pnmsplit split a multi-image Netpbm file into multiple 1-image files pnmindex build a visual index of a bunch of Netpbm images pnmmontage build multiple Netpbm images into a single montage image pgmbentley Bentleyize a PGM image pgmcrater create cratered terrain by fractal forgery pamoil turn a PNM or PAM image into an oil painting ppmforge fractal forgeries of clouds, planets, and starry skies pgmkernel generate a convolution kernel ppmtv Make an image lined so it looks like an old TV pampop9 simulate a multi-lens camera such as the Pop9 Obsolete Names There used to be programs by the following names. Each has been either renamed to a more illustrative name, or superseded by a more general function. In most cases, Netpbm is installed with symbolic links that allow old programs and procedures to use these names but run the replacement programs: ppmtotga pnmnoraw gemtopbm pnminterp pgmoil ppmtojpeg bmptoppm pgmnorm ppmnorm pnmfile pnmarith pgmedge pnmtoplainpnm øpnmtopnm Updated: 31 May 2004 Table Of Contents NAME pnmtopnm - copy a PNM image SYNOPSIS pnmtopnm [pnmfile] DESCRIPTION This program is part of Netpbm. pnmtopnm simply copies a PNM image to Standard Output. The output has the same major PNM format (PBM, PGM, or PPM) and maxval as the input. This may seem an unnecessary duplication of cat, but it lets you convert between the plain (ASCII) and raw (binary) subformats of PNM. Use the -plain Netpbm common option to ensure the output is plain PNM, and don't use -plain to ensure the output is raw PNM. See Common Options. You don't normally need to convert between the PNM subformats, because any program that uses the Netpbm library to read a PNM image will read all of them directly. But there are a lot of programs that don't use the Netpbm library and understand only the raw format. Plain format is nice because it is human readable; people often use it to debug programs that process PNM images. HISTORY pnmtopnm was new in Netpbm 10.23 (July 2004). It obsoleted pnmtoplainpnm, which specifically did the conversion to plain PNM. There was no program to explicitly convert to raw PNM, but many Netpbm programs can be made, with the right options, to be idempotent (i.e. to do the same thing as pnmtopnm). SEE ALSO ppmtoppm pgmtopgm pnm Table Of Contents NAME SYNOPSIS DESCRIPTION SEE ALSO øpgmtopgm Updated: September 2002 Table Of Contents NAME pgmtopgm - copy PGM image SYNOPSIS pgmtopgm DESCRIPTION This program is part of Netpbm. pgmtopgm simply copies a PGM image from Standard Input to Standard Output. This may seem an unnecessary duplication of cat, but remember that a PGM program can read a PBM image as if it were PGM. So pgmtopgm can read either a PBM or PGM image and produce a PGM image as output. Even that is of limited usefulness because of the fact that almost any program to which you would feed the resulting PGM image could also just take the original image directly. However, sometimes you really need a true PGM image. When you know you have a PBM image and want a PGM image, pbmtopgm is a more general way to do that conversion. SEE ALSO ppmtoppm, pnmtopnm, pamtopnm, pbmtopgm, pgm, pgm, HISTORY This program was added to Netpbm in Release 10.9 (September 2002). Table Of Contents NAME SYNOPSIS DESCRIPTION SEE ALSO HISTORY øpbmtopgm Updated: 05 Feb 2003 Table Of Contents NAME pbmtopgm - convert PBM image to PGM by averaging areas SYNOPSIS pbmtopgm width height [pbmfile] DESCRIPTION This program is part of Netpbm. pbmtopgm reads a PBM image as input. It outputs a PGM image in which each pixel's gray level is the average of the surrounding black and white input pixels. The surrounding area is a rectangle of width by height pixels. In other words, this is a convolution. pbmtopgm is similar to a special case of pnmconvol. You may need a pnmsmooth step after pbmtopgm. pbmtopgm has the effect of anti-aliasing bitmaps which contain distinct line features. pbmtopgm works best with odd sample width and heights. You don't need pbmtopgm just to use a PGM program on a PBM image. Any PGM program (assuming it uses the Netpbm libraries to read the PGM input) takes PBM input as if it were PGM, with only the mininum and maximum gray levels. So unless your convolution rectangle is bigger than one pixel, you're not gaining anything with a pbmtopgm step. The opposite transformation (which would turn a PGM into a PBM) is dithering. See pamditherbw. SEE ALSO pamditherbw, pnmconvol, pbm, pgm 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 documentation. This software is provided "as is" without express or implied warranty. Table Of Contents NAME SYNOPSIS DESCRIPTION SEE ALSO AUTHOR øpgmtopbm Updated: 20 June 2004 Table Of Contents NAME pgmtopbm - convert a PGM image to PBM SYNOPSIS pgmtopbm [-floyd | -fs | -threshold | -hilbert | -dither8 | -d8 | -cluster3 | -c3 | -cluster4 | -c4 | -cluster8 | -c8] [-value val] [-clump size] [pgmfile] DESCRIPTION This program is part of Netpbm. This program is obsolete since Netpbm 10.23 (July 2004). Use pamditherbw to do what this program used to do. pgmtopbm never was the simple converter it appeared to be. It was a dithering program. Unfortunately, it didn't do the dithering properly because it treated the PGM input samples as if they were directly proportional to light intensity, but they are actually gamma-adjusted. pamditherbw is backward compatible with pgmtopbm except that it does the correct gamma adjustments. øpgmtoppm Updated: 24 January 2001 Table Of Contents NAME pgmtoppm - colorize a PGM (grayscale) image into a PPM (color) image SYNOPSIS pgmtoppm colorspec [pgmfile] pgmtoppm colorspec1-colorspec2 [pgmfile] pgmtoppm -map mapfile [pgmfile] DESCRIPTION This program is part of Netpbm. pgmtoppm reads a PGM as input and produces a PPM file as output with a specific color assigned to each gray value in the input. If you specify one color argument, black in the pgm file stays black and white in the pgm file turns into the specified color in the ppm file. Gray values in between are linearly mapped to differing intensities of the specified color. If you specify two color arguments (separated by a dash), then black gets mapped to the first color and white gets mapped to the second and gray values in between get mapped linearly (across a three dimensional space) to colors in between. Specify the color (color) as described for the argument of the ppm_parsecolor() library routine. Also, you can specify an entire colormap with the -map option. 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 and gray values in between are mapped linearly onto the sequence of colors in between. A more direct way to specify a particular color to replace each particular gray level is to use pamlookup. You make an index file that explicitly associates a color with each possible gray level. NOTE - MAXVAL The "maxval," or depth, of the output image is the same as that of the input image. The maxval affects the color resolution, which may cause quantization errors you don't anticipate in your output. For example, you have a simple black and white image as a PGM with maxval 1. Run this image through pgmtoppm 0f/00/00 to try to make the image black and faint red. Because the output image will also have maxval 1, there is no such thing as faint red. It has to be either full-on red or black. pgmtoppm rounds the color 0f/00/00 down to black, and you get an output image that is nothing but black. The fix is easy: Pass the input through pnmdepth on the way into pgmtoppm to increase its depth to something that would give you the resolution you need to get your desired color. In this case, pnmdepth 16 would do it. Or spare yourself the unnecessary thinking and just say pnmdepth 255 . PBM input is a special case. While you might think this would be equivalent to a PGM with maxval 1 since only two gray levels are necessary to represent a PBM image, pgmtoppm, like all Netpbm programs, in fact treats it as a maxval of 255. SEE ALSO pnmdepth, rgb3toppm, ppmtopgm, ppmtorgb3, ppm, pgm AUTHOR Copyright (C) 1991 by Jef Poskanzer. Table Of Contents NAME SYNOPSIS DESCRIPTION NOTE - MAXVAL SEE ALSO AUTHOR øppmtopgm Updated: 10 April 2000 Table Of Contents NAME ppmtopgm - convert a PPM image to a PGM image SYNOPSIS ppmtopgm [ppmfile] DESCRIPTION This program is part of Netpbm. ppmtopgm reads a PPM as input and produces a PGM as output. The output is a "black and white" rendering of the original image, as in a black and white photograph. The quantization formula ppmtopgm uses is g = .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 automatically. pgmtoppm is for colorizing a pgm file. Also, see ppmtorgb3 for a different way of converting color to gray. And ppmdist generates a grayscale image from a color image, but in a way that makes it easy to differentiate the original colors, not necessarily a way that looks like a black and white photograph. QUOTE Cold-hearted orb that rules the night Removes the colors from our sight Red is gray, and yellow white But we decide which is right And which is a quantization error. SEE ALSO pgmtoppm, ppmtorgb3, rgb3toppm, ppmdist, ppm, pgm AUTHOR Copyright (C) 1989 by Jef Poskanzer. Table Of Contents NAME SYNOPSIS DESCRIPTION QUOTE SEE ALSO AUTHOR øJPEGTOPNM Updated: 13 October 2002 Table Of Contents NAME jpegtopnm - convert JPEG/JFIF file to PPM or PGM image SYNOPSIS jpegtopnm [-dct {int|fast|float}] [-nosmooth] [-maxmemory N] [{-adobe|-notadobe}] [-comments] [-dumpexif] [-exif=filespec] [-multiple] [-verbose] [-tracelevel N] [filename] Minimum unique abbreviation of option is acceptable. You may use double hypens instead of single hyphen to denote options. You may use white space in place of the equals sign to separate an option name from its value. DESCRIPTION This program is part of Netpbm. jpegtopnm converts JFIF images to PPM or PGM images. By default, jpegtopnm expects the input stream to contain one JFIF image and produces one PGM or PPM image as output. It fails if the input stream is empty. But with the -multiple option, jpegtopnm reads JFIF images sequentially from the input stream and writes one PPM or PGM image to the output stream for each JFIF input. If the input stream is empty, so is the output. The input stream is the filename you specify or, if you don't specify filename, Standard Input. The output stream is Standard Output. If a JFIF input image is of the grayscale variety, jpegtopnm generates a PGM image. Otherwise, it generates a PPM image. Before Netpbm 10.11 (October 2002), jpegtopnm did not have the multiple image stream capability. From 10.11 through 10.22, Netpbm always behaved as if you specified -multiple. Starting with Netpbm 10.23 (July 2004), Netpbm's default behavior went back to the pre-10.11 behavior and the new -multiple option selected the 10.12 behavior. The reason for the reversion was that there were discovered in the world files that contain JFIF images followed by something other than another JFIF image. The producers of these files expect them to work with any JFIF interpreter because most JFIF interpreters just stop reading the file after the first JFIF image. jpegtopnm uses the Independent JPEG Group's JPEG library to interpret the input file. See http://www.ijg.org for information on the library. "JFIF" is the correct name for the image format commonly known as "JPEG." Strictly speaking, JPEG is a method of compression. The image format using JPEG compression that is by far the most common is JFIF. There is also a subformat of TIFF that uses JPEG compression. EXIF is an image format that is a subformat of JFIF (to wit, a JFIF file that contains an EXIF header as an APP1 marker). jpegtopnm handles EXIF. JFIF files can have either 8 bits per sample or 12 bits per sample. The 8 bit variety is by far the most common. There are two versions of the IJG JPEG library. One reads only 8 bit files and the other reads only 12 bit files. You must link the appropriate one of these libraries with jpegtopnm. Ordinarily, this means the library is in your shared library search path when you run jpegtopnm. jpegtopnm generates output with either one byte or two bytes per sample depending on whether the JFIF input has either 8 bits or 12 bits per sample. You can use pnmdepth to reduce a two-byte-per-sample file to a one-byte-per-sample file if you need to. If the JFIF file uses the CMYK or YCCK color space, the input does not actually contain enough information to know what color each pixel is. To know what color a pixel is, one would have to know the properties of the inks to which the color space refers. jpegtopnm interprets the colors using the common transformation which assumes all the inks are simply subtractive and linear. See the jpegtopnm manual for information on how images lose quality when you convert to and from JFIF. OPTIONS The options are only for advanced users: -dct int Use integer DCT method (default). -dct fast Use fast integer DCT (less accurate). -dct float Use floating-point DCT method. The float method is very slightly more accurate than the int method, but is much slower unless your machine has very fast floating-point hardware. Also note that results of the floating-point method may vary slightly across machines, while the integer methods should give the same results everywhere. The fast integer method is much less accurate than the other two. -nosmooth Use a faster, lower-quality upsampling routine. -maxmemory N Set limit on the amount of memory jpegtopnm uses in processing large images. Value is in thousands of bytes, or millions of bytes if "M" is suffixed to the number. For example, -maxmemory 4m selects 4000000 bytes. If jpegtopnm needs more space, it uses temporary files. -adobe -notadobe There are two variations on the CMYK (and likewise YCCK) color space that may be used in the JFIF input. In the normal one, a zero value for a color components indicates absence of ink. In the other, a zero value means the maximum ink coverage. The latter is used by Adobe Photoshop when it creates a bare JFIF output file (but not when it creates JFIF output as part of Encapsulated Postscript output). These options tell jpegtopnm which version of the CMYK or YCCK color space the image uses. If you specify neither, jpegtopnm tries to figure it out on its own. In the present version, it doesn't try very hard at all: It just assumes the Photoshop version, since Photoshop and its emulators seem to be the main source of CMYK and YCCK images. But with experience of use, future versions might be more sophisticated. If the JFIF image does not indicate that it is CMYK or YCCK, these options have no effect. If you don't use the right one of these options, the symptom is output that looks like a negative. -dumpexif Print the interpreted contents of any Exif header in the input file to the Standard Error file. Similar to the program jhead (not part of the Netpbm package). This option was added in Netpbm 9.19 (September 2001). -exif=filespec Extract the contents of the EXIF header from the input image and write it to the file filespec. filespec=- means write it to Standard Output. When you write the EXIF header to Standard Output, jpegtopnm does not output the converted image (which is what normally would go to Standard Output) at all. jpegtopnm writes the contents of the EXIF header byte-for-byte, starting with the two byte length field (which length includes those two bytes). You can use this file as input to pnmtojpeg to insert an identical EXIF header into a new JFIF image. If there is no EXIF header, jpegtopnm writes two bytes of binary zero and nothing else. An EXIF header takes the form of a JFIF APP1 marker. Only the first such marker within the JFIF header counts. This option was added in Netpbm 9.19 (September 2001). -multiple Read multiple JFIF images sequentially from the input stream. See Description section for details. This option was new in Netpbm 10.23 (July 2004). -comments Print any comments in the input file to the Standard Error file. -verbose Print details about the conversion to the Standard Error file. -tracelevel n Turn on the JPEG library's trace messages to the Standard Error file. A higher value of n gets more trace information. -verbose implies a trace level of at least 1. EXAMPLES This example converts the color JFIF file foo.jpg to a PPM file named foo.ppm: jpegtopnm foo.jpg >foo.ppm HINTS You can use pnmquant to color quantize the result, i.e. to reduce the number of distinct colors in the image. In fact, you may have to if you want to convert the PPM file to certain other formats. ppmdither Does a more sophisticated quantization. Use pamscale to change the dimensions of the resulting image. Use ppmtopgm to convert a color JFIF file to a grayscale PGM file. You can easily use these converters together. E.g.: jpegtopnm foo.jpg | ppmtopgm | pamscale .25 >foo.pgm -dct fast and/or -nosmooth gain speed at a small sacrifice in quality. If you are fortunate enough to have very fast floating point hardware, -dct float may be even faster than -dct fast. But on most machines -dct float is slower than -dct int; in this case it is not worth using, because its theoretical accuracy advantage is too small to be significant in practice. Another program, djpeg, is similar. djpeg is maintained by the Independent JPEG Group and packaged with the JPEG library which jpegtopnm uses for all its JPEG work. Because of that, you may expect it to exploit more current JPEG features. Also, since you have to have the library to run jpegtopnm, but not vice versa, cjpeg may be more commonly available. On the other hand, djpeg does not use the NetPBM libraries to generate its output, as all the NetPBM tools such as jpegtopnm do. This means it is less likely to be consistent with all the other programs that deal with the NetPBM formats. Also, the command syntax of jpegtopnm is consistent with that of the other Netpbm tools, unlike djpeg. ENVIRONMENT JPEGMEM If this environment variable is set, its value is the default memory limit. The value is specified as described for the -maxmemory option. An explicit -maxmemory option overrides any JPEGMEM. SEE ALSO ppm, pgm, pnmtojpeg, pnmquant, pamscale, ppmtopgm, ppmdither, pnmdepth, djpeg man page, cjpeg man page, jpegtran man page, rdjpgcom man page, wrjpgcom man page, jhead man page Wallace, Gregory K. "The JPEG Still Picture Compression Standard", Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44. LIMITATIONS Arithmetic coding is not offered for legal reasons. The program could be much faster. AUTHOR jpegtopnm and this manual were derived in large part from djpeg, by the Independent JPEG Group. The program is otherwise by Bryan Henderson on March 19, 2000. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS EXAMPLES HINTS ENVIRONMENT SEE ALSO LIMITATIONS AUTHOR øPNMTOJPEG Updated: 18 February 2005 Table Of Contents NAME pnmtojpeg - convert PNM image to a JFIF ("JPEG") image SYNOPSIS pnmtojpeg [-exif=filespec] [-quality=n] [{-grayscale|-greyscale}] [-density=nxn[dpi,dpcm]] [-optimize|-optimise] [-rgb] [-progressive] [-comment=text] [-dct={int|fast|float}] [-arithmetic] [-restart=n] [-smooth=n] [-maxmemory=n] [-verbose] [-baseline] [-qtables=filespec] [-qslots=n[,...]] [-sample=HxV[,...]] [-scans=filespec] [-tracelevel=N] filename Minimum unique abbreviation of option is acceptable. You may use double hypens instead of single hyphen to denote options. You may use white space in place of the equals sign to separate an option name from its value. DESCRIPTION This program is part of Netpbm. pnmtojpeg converts the named PBM, PGM, or PPM image file, or the standard input if no file is named, to a JFIF file on the standard output. pnmtojpeg uses the Independent JPEG Group's JPEG library to create the output file. See http://www.ijg.org for information on the library. "JFIF" is the correct name for the image format commonly known as "JPEG." Strictly speaking, JPEG is a method of compression. The image format using JPEG compression that is by far the most common is JFIF. There is also a subformat of TIFF that uses JPEG compression. EXIF is an image format that is a subformat of JFIF (to wit, a JFIF file that contains an EXIF header as an APP1 marker). pnmtojpeg creates an EXIF image when you specify the -exif option. OPTIONS The basic options are: -exif=filespec This option specifies that the output image is to be EXIF (a subformat of JFIF), i.e. it will have an EXIF header as a JFIF APP1 marker. The contents of that marker are the contents of the specified file. The special value - means to read the EXIF header contents from standard input. It is invalid to specify standard input for both the EXIF header and the input image. The EXIF file starts with a two byte field which is the length of the file, including the length field, in pure binary, most significant byte first. The special value of zero for the length field means there is to be no EXIF header, i.e. the same as no -exif option. This is useful for when you convert a file from JFIF to PNM using jpegtopnm, then transform it, then convert it back to JFIF with pnmtojpeg, and you don't know whether or not it includes an EXIF header. jpegtopnm creates an EXIF file containing nothing but two bytes of zero when the input JFIF file has no EXIF header. Thus, you can transfer any EXIF header from the input JFIF to the output JFIF without worrying about whether an EXIF header actually exists. The contents of the EXIF file after the length field are the exact byte for byte contents of the APP1 marker, not counting the length field, that constitutes the EXIF header. -quality=n Scale quantization tables to adjust image quality. n is 0 (worst) to 100 (best); default is 75. (See below for more info.) -grayscale -greyscale -rgb These options determine the color space used in the JFIF output. -grayscale (or -greyscale) means to create a gray scale JFIF, converting from color PPM input if necessary. -rgb means to create an RGB JFIF, and the program fails if the input is not PPM. If you specify neither, The output file is in YCbCr format if the input is PPM, and grayscale format if the input is PBM or PGM. YCbCr format (a color is represented by an intensity value and two chrominance values) usually compresses much better than RGB (a color is represented by one red, one green, and one blue value). RGB is rare. But you may be able to convert between JFIF and PPM faster with RGB, since it's the same color space PPM uses. The testimg.ppm file that comes with Netpbm is 2.3 times larger with the -rgb option that with the YCbCr default, and in one experiment pnmtojpeg took 16% more CPU time to convert it. The extra CPU time probably indicates that processing of all the extra compressed data consumed all the CPU time saved by not having to convert the RGB inputs to YCbCr. Grayscale format takes up a lot less space and takes less time to create and process than the color formats, even if the image contains nothing but black, white, and gray. The -rgb option was added in Netpbm 10.11 in October 2002. -density=density This option determines the density (aka resolution) information recorded in the JFIF output image. It does not affect the raster in any way; it just tells whoever reads the JFIF how to interpret the raster. The density value takes the form xxy followed by an optional unit specifier of dpi or dpcm. Examples: 1x1, 3x2, 300x300dpi, 100x200dpcm. The first number is the horizontal density; the 2nd number is the vertical density. Each may be any integer from 1 to 65535. The unit specifier is dpi for dots per inch or dpcm for dots per centimeter. If you don't specify the units, the density information goes into the JFIF explicitly stating "density unspecified" (also interpreted as "unknown"). This may seem pointless, but note that even without specifying the units, the density numbers tell the aspect ratio of the pixels. E.g. 1x1 tells you the pixels are square. 3x2 tells you the pixels are horizontal rectangles. Note that if you specify different horizontal and vertical densities, the resulting JFIF image is not a true representation of the input PNM image, because pnmtojpeg converts the raster pixel-for-pixel and the pixels of a PNM image are defined to be square. Thus, if you start with a square PNM image and specify -density=3x2, the resulting JFIF image is a vertically squashed version of the original. However, it is common to use an input image which is a slight variation on PNM rather than true PNM such that the pixels are not square. In that case, the appropriate -density option yields a faithful reproduction of the input pseudo-PNM image. The default is 1x1 in unspecified units. Before Netpbm 10.15 (April 2003), this option did not exist and the pnmtojpeg always created a JFIF with a density of 1x1 in unspecified units. -optimize Perform optimization of entropy encoding parameters. Without this, pnmtojpeg uses default encoding parameters. -optimize usually makes the JFIF file a little smaller, but pnmtojpeg runs somewhat slower and needs much more memory. Image quality and speed of decompression are unaffected by -optimize. -progressive Create a progressive JPEG file (see below). -comment=text Include a comment marker in the JFIF output, with comment text text. Without this option, there are no comment markers in the output. The -quality option lets you trade off compressed file size against quality of the reconstructed image: the higher the quality setting, the larger the JFIF file, and the closer the output image will be to the original input. Normally you want to use the lowest quality setting (smallest file) that decompresses into something visually indistinguishable from the original image. For this purpose the quality setting should be between 50 and 95; the default of 75 is often about right. If you see defects at -quality=75, then go up 5 or 10 counts at a time until you are happy with the output image. (The optimal setting will vary from one image to another.) -quality=100 generates a quantization table of all 1's, minimizing loss in the quantization step (but there is still information loss in subsampling, as well as roundoff error). This setting is mainly of interest for experimental purposes. Quality values above about 95 are not recommended for normal use; the compressed file size goes up dramatically for hardly any gain in output image quality. In the other direction, quality values below 50 will produce very small files of low image quality. Settings around 5 to 10 might be useful in preparing an index of a large image library, for example. Try -quality=2 (or so) for some amusing Cubist effects. (Note: quality values below about 25 generate 2-byte quantization tables, which are considered optional in the JFIF standard. pnmtojpeg emits a warning message when you give such a quality value, because some other JFIF programs may be unable to decode the resulting file. Use -baseline if you need to ensure compatibility at low quality values.) The -progressive option creates a "progressive JPEG" file. In this type of JFIF file, the data is stored in multiple scans of increasing quality. If the file is being transmitted over a slow communications link, the decoder can use the first scan to display a low-quality image very quickly, and can then improve the display with each subsequent scan. The final image is exactly equivalent to a standard JFIF file of the same quality setting, and the total file size is about the same -- often a little smaller. Caution: progressive JPEG is not yet widely implemented, so many decoders will be unable to view a progressive JPEG file at all. If you're trying to control the quality/file size tradeoff, you might consider the JPEG2000 format instead. See pamtojpeg2k. Options for advanced users: -dct=int Use integer DCT method (default). -dct=fast Use fast integer DCT (less accurate). -dct=float Use floating-point DCT method. The float method is very slightly more accurate than the int method, but is much slower unless your machine has very fast floating-point hardware. Also note that results of the floating-point method may vary slightly across machines, while the integer methods should give the same results everywhere. The fast integer method is much less accurate than the other two. -arithmetic Use arithmetic coding. Default is Huffman encoding. Arithmetic coding tends to get you a smaller result. You may need patent licenses to use this option. According to the JPEG FAQ, This method is covered by patents owned by IBM, AT&T, and Mitsubishi. The author of the FAQ recommends against using arithmetic coding (and therefore this option) because the space savings is not great enough to justify the legal hassles. -restart=n Emit a JPEG restart marker every n MCU rows, or every n MCU blocks if you append B to the number. -restart 0 (the default) means no restart markers. -smooth=n Smooth the input image to eliminate dithering noise. n, ranging from 1 to 100, indicates the strength of smoothing. 0 (the default) means no smoothing. -maxmemory=n Set a limit for amount of memory to use in processing large images. Value is in thousands of bytes, or millions of bytes if you append M to the number. For example, -max=4m selects 4,000,000 bytes. If pnmtojpeg needs more space, it will use temporary files. -verbose Print to the Standard Error file messages about the conversion process. This can be helpful in debugging problems. The -restart option tells pnmtojpeg to insert extra markers that allow a JPEG decoder to resynchronize after a transmission error. Without restart markers, any damage to a compressed file will usually ruin the image from the point of the error to the end of the image; with restart markers, the damage is usually confined to the portion of the image up to the next restart marker. Of course, the restart markers occupy extra space. We recommend -restart=1 for images that will be transmitted across unreliable networks such as Usenet. The -smooth option filters the input to eliminate fine-scale noise. This is often useful when converting dithered images to JFIF: a moderate smoothing factor of 10 to 50 gets rid of dithering patterns in the input file, resulting in a smaller JFIF file and a better-looking image. Too large a smoothing factor will visibly blur the image, however. Options for wizards: -baseline Force baseline-compatible quantization tables to be generated. This clamps quantization values to 8 bits even at low quality settings. (This switch is poorly named, since it does not ensure that the output is actually baseline JPEG. For example, you can use -baseline and -progressive together.) -qtables=filespec Use the quantization tables given in the specified text file. -qslots=n[,...] Select which quantization table to use for each color component. -sample=HxV[,...] Set JPEG sampling factors for each color component. -scans=filespec Use the scan script given in the specified text file. See below for information on scan scripts. -tracelevel=N This sets the level of debug tracing the program outputs as it runs. 0 means none, and is the default. This level primarily controls tracing of the JPEG library, and you can get some pretty interesting information about the compression process. The "wizard" options are intended for experimentation with JPEG. If you don't know what you are doing, don't use them. These switches are documented further in the file wizard.doc that comes with the Independent JPEG Group's JPEG library. EXAMPLES This example compresses the PPM file foo.ppm with a quality factor of 60 and saves the output as foo.jpg: pnmtojpeg -quality=60 foo.ppm > foo.jpg Here's a more typical example. It converts from BMP to JFIF: cat foo.bmp | bmptoppm | pnmtojpeg > foo.jpg JPEG Loss When you compress with JPEG, you lose information -- i.e. the resulting image has somewhat lower quality than the original. This is a characteristic of JPEG itself, not any particular program. So if you do the usual Netpbm thing and convert from JFIF to PNM, manipulate, then convert back to JFIF, you will lose quality. The more you do it, the more you lose. Drawings (charts, cartoons, line drawings, and such with few colors and sharp edges) suffer the most. To avoid this, you can use a compressed image format other than JPEG. PNG and JPEG2000 are good choices, and Netpbm contains converters for those. If you need to use JFIF on a drawing, you should experiment with pnmtojpeg's -quality and -smooth options to get a satisfactory conversion. -smooth 10 or so is often helpful. Because of the loss, you should do all the manipulation you have to do on the image in some other format and convert to JFIF as the last step. And if you can keep a copy in the original format, so much the better. The -optimize option to pnmtojpeg is worth using when you are making a "final" version for posting or archiving. It's also a win when you are using low quality settings to make very small JFIF files; the percentage improvement is often a lot more than it is on larger files. (At present, -optimize mode is automatically in effect when you generate a progressive JPEG file). You can do flipping and rotating transformations losslessly with the program jpegtran, which is packaged with the Independent Jpeg Group's JPEG library. jpegtran exercises its intimate knowledge of the way JPEG works to do the transformation without ever actually decompressing the image. Another program, cjpeg, is similar. cjpeg is maintained by the Independent JPEG Group and packaged with the JPEG library which pnmtojpeg uses for all its JPEG work. Because of that, you may expect it to exploit more current JPEG features. Also, since you have to have the library to run pnmtojpeg, but not vice versa, cjpeg may be more commonly available. On the other hand, cjpeg does not use the NetPBM libraries to process its input, as all the NetPBM tools such as pnmtojpeg do. This means it is less likely to be consistent with all the other programs that deal with the NetPBM formats. Also, the command syntax of pnmtojpeg is consistent with that of the other Netpbm tools, unlike cjpeg. SCAN SCRIPTS Use the -scan option to specify a scan script. Or use the -progressive option to specify a particular built-in scan script. Just what a scan script is, and the basic format of the scan script file, is covered in the wizard.doc file that comes with the Independent JPEG Group's JPEG library. Scan scripts are same for pnmtojpeg as the are for cjpeg. This section contains additional information that isn't, but probably should be, in that document. First, there are many restrictions on what is a valid scan script. The JPEG library, and thus pnmtojpeg, checks thoroughly for any lack of compliance with these restrictions, but does little to tell you how the script fails to comply. The messages are very general and sometimes untrue. To start with, the entries for the DC coefficient must come before any entries for the AC coefficients. The DC coefficient is Coefficient 0; all the other coefficients are AC coefficients. So in an entry for the DC coefficient, the two numbers after the colon must be 0 and 0. In an entry for AC coefficients, the first number after the colon must not be 0. In a DC entry, the color components must be in increasing order. E.g. "0,2,1" before the colon is wrong. So is "0,0,0". In an entry for an AC coeffient, you must specify only one color component. I.e. there can be only one number before the colon. In the first entry for a particular coefficient for a particular color component, the "Ah" value must be zero, but the Al value can be any valid bit number. In subsequent entries, Ah must be the Al value from the previous entry (for that coefficient for that color component), and the Al value must be one less than the Ah value. The script must ultimately specify at least some of the DC coefficent for every color component. Otherwise, you get the error message "Script does not transmit all the data." You need not specify all of the bits of the DC coefficient, or any of the AC coefficients. There is a standard option in building the JPEG library to omit scan script capability. If for some reason your library was built with this option, you get the message "Requested feature was omitted at compile time." ENVIRONMENT JPEGMEM If this environment variable is set, its value is the default memory limit. The value is specified as described for the -maxmemory option. An explicit -maxmemory option overrides any JPEGMEM. SEE ALSO jpegtopnm, pnm, cjpeg man page, djpeg man page, jpegtran man page, rdjpgcom man page, wrjpgcom man page Wallace, Gregory K. "The JPEG Still Picture Compression Standard", Communications of the ACM, April 1991 (vol. 34, no. 4), pp. 30-44. AUTHOR pnmtojpeg and this manual were derived in large part from cjpeg, by the Independent JPEG Group. The program is otherwise by Bryan Henderson on March 07, 2000. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS EXAMPLES JPEG LOSS OTHER PROGRAMS SCAN SCRIPTS ENVIRONMENT SEE ALSO AUTHOR øbmptopnm Updated: 17 February 2002 Table Of Contents NAME bmptopnm - convert a BMP file into a PBM, PGM, or PNM image SYNOPSIS bmptopnm [bmpfile] DESCRIPTION This program is part of Netpbm. bmptopnm reads a Microsoft Windows or OS/2 BMP file as input. and produces a PBM, PGM, or PNM image as output. If the input is colormapped and contains only black and white, the output is PBM. If the input is colormapped and contains only black white and gray, the output is PGM. Otherwise, the output is PPM. This program cannot convert BMP files with compressed (run length encoded, JPEG, PNG) image data. It recognizes the compression and issues an error message. Before Netpbm 10.18 (September 2003), this program could not convert BMP images with the BI_BITFIELDS format ("compression type"). It would recognize the format and issue an error message. This program cannot convert OS/2 BMP files with 16 bits per pixel (only because the author did not have a complete specification for them). It recognizes the format and issues an error message. Before Netpbm 10.16 (June 2003), it also could not convert Windows BMP files with 16 bits per pixel. SEE ALSO ppmtobmp, ppmtowinicon, ppm AUTHOR Copyright (C) 1992 by David W. Sanderson. Table Of Contents NAME SYNOPSIS DESCRIPTION SEE ALSO AUTHOR øppmtobmp Updated: 13 June 2000 Table Of Contents NAME ppmtobmp - convert a PPM image into a BMP file SYNOPSIS ppmtobmp [-windows] [-os2] [-bpp=bits_per_pixel] [ppmfile] Minimum unique abbreviation of option is acceptable. You may use double hyphens instead of single hyphen to denote options. You may use white space in place of the equals sign to separate an option name from its value. DESCRIPTION This program is part of Netpbm. ppmtobmp reads a PPM image as input and produces a Microsoft Windows or OS/2 BMP file as output. OPTIONS -windows Tells the program to produce a Microsoft Windows BMP file. (This is the default.) -os2 Tells the program to produce an OS/2 BMP file. (Before August 2000, this was the default). -bpp This tells how many bits per pixel you want the BMP file to contain. Only 1, 4, 8, and 24 are possible. By default, ppmtobmp chooses the smallest number with which it can represent all the colors in the input image. If you specify a number too small to represent all the colors in the input image, ppmtobmp tells you and terminates. You can use pnmquant or ppmdither to reduce the number of colors in the image. NOTES To get a faithful reproduction of the input image, the maxval of the input image must be 255. If it is something else, the colors in the BMP file may be slightly different from the colors in the input. Windows icons are not BMP files. Use ppmtowinicon to create those. SEE ALSO bmptoppm, ppmtowinicon, pnmquant, ppmdither, ppm AUTHOR Copyright (C) 1992 by David W. Sanderson. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS NOTES SEE ALSO AUTHOR grafx2 formater er GIF, BMP, PCX, LBM øppmtopcx Updated: 27 March 2004 Table Of Contents NAME ppmtopcx - convert a PPM image to a PCX file SYNOPSIS ppmtopcx [-24bit] [-8bit] [-packed] [-stdpalette] [-palette=palettefile] [-planes=planes] [-xpos=cols] [-ypos=rows] [ppmfile] DESCRIPTION This program is part of Netpbm. ppmtopcx reads a PPM image as input and produces a PCX file as output. The type of the PCX file depends on the number of colors in the pixmap: 16 colors or fewer: 1 bit/pixel, 1-4 planes. more than 16 colors, but no more than 256: 8 bits/pixel, 1 plane, colormap at the end of the file. More than 256 colors: 24bit truecolor file (8 bits/pixel, 3 planes). You can override some of that and explicitly choose the format with the options below. OPTIONS -24bit Produce a 24bit truecolor PCX file, even if the image has 256 colors or fewer. -8bit Produce an 8bit (256 colors) PCX file, even if the image has 16 colors or fewer. This option was added in Netpbm 10.18 (August 2003). -packed Use "packed pixel" format for files with 16 colors or fewer: 1, 2, or 4 bits/pixel, 1 plane. -stdpalette Instead of computing a palette from the colors in the image, use a standard, built-in 16 color palette. If the image contains a color that is not in the standard palette, ppmtopcx fails. The standard palette is not only a set of colors, but a specific mapping of palette indexes to colors. E.g. red is 4. You can use pnmremap with a suitable PPM image of the standard palette to adapt your image to use exactly those colors in the palette so that ppmtopcx -stdpalette will work on it. The file pcxstd.ppm, part of Netpbm, contains the standard palette. Although the PCX header tells exactly what palette is used in the file, some older PCX interpreters do not use that information. They instead assume the standard palette. If you don't use the -stdpalette option, ppmtopcx, ppmtopcx may create an image that uses a different palette (a rearrangement of the same colors) and then one of these older interpreters would interpret the colors in the image wrong. You cannot specify this option along with -palette. This option was new in Netpbm 10.22 (April 2004). -palette=palettefile Instead of computing the palette from the colors in the image, use the palette from the file palettefile. If the palette contains a color that is not in that palette, ppmtopcx fails. The palette file must be a PPM image that contains one pixel for each color in the palette. It doesn't matter what the aspect ratio of the palette image is. The order of the colors in the PCX palette is the order of the pixels in the PPM image in standard western reading order (left to right, top to bottom). If there is a duplicate color in the palette, ppmtopcx chooses between them arbitrarily in building the PCX raster. You would need this only if you have a PCX reader that can't read the palette that is in the PCX file and instead assumes some particular palette. See also the -stdpalette option. If your input image might contain colors other than those in your palette, you can convert the input image to one that contains only those colors in your palette with pnmremap. You cannot specify this along with -stdpalette. This option was new in Netpbhm 10.25 (October 2004). -planes=planes Generate a PCX file with planes planes, even though the number of colors in the image could be represented in fewer. This makes the file larger, but some PCX interpreters are capable of processing only certain numbers of planes. This is meaningful only when ppmtopcx generates an image in the 16 color palette format without packed pixels. Consequently, you cannot specify this option together with -24bit or -8bit or -packed. The valid values for planes are 1, 2, 3, and 4. By default, ppmtopcx chooses the smallest number of planes that can represent the colors in the image. E.g. if there are 5 colors, ppmtopcx chooses 3 planes. This option was new in Netpbm 10.21 (March 2004). -xpos=cols -ypos=rows These options set the position of the image in some field (e.g. on a screen) in columns to the right of the left edge and rows below the top edge. The PCX format contains image position information. Don't confuse this with the position of an area of interest within the image. For example, using pnmpad to add a 10 pixel left border to an image and then converting that image to PCX with xpos = 0 is not the same as converting the original image to PCX and setting xpos = 10. The values may be from -32767 to 32768. The default for each is zero. SEE ALSO pcxtoppm, ppm AUTHORS Copyright (C) 1994 by Ingo Wilken (Ingo.Wilken@informatik.uni-oldenburg.de) Based on previous work by Michael Davidson. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO AUTHORS øppmtopcx Updated: 27 March 2004 Table Of Contents NAME ppmtopcx - convert a PPM image to a PCX file SYNOPSIS ppmtopcx [-24bit] [-8bit] [-packed] [-stdpalette] [-palette=palettefile] [-planes=planes] [-xpos=cols] [-ypos=rows] [ppmfile] DESCRIPTION This program is part of Netpbm. ppmtopcx reads a PPM image as input and produces a PCX file as output. The type of the PCX file depends on the number of colors in the pixmap: 16 colors or fewer: 1 bit/pixel, 1-4 planes. more than 16 colors, but no more than 256: 8 bits/pixel, 1 plane, colormap at the end of the file. More than 256 colors: 24bit truecolor file (8 bits/pixel, 3 planes). You can override some of that and explicitly choose the format with the options below. OPTIONS -24bit Produce a 24bit truecolor PCX file, even if the image has 256 colors or fewer. -8bit Produce an 8bit (256 colors) PCX file, even if the image has 16 colors or fewer. This option was added in Netpbm 10.18 (August 2003). -packed Use "packed pixel" format for files with 16 colors or fewer: 1, 2, or 4 bits/pixel, 1 plane. -stdpalette Instead of computing a palette from the colors in the image, use a standard, built-in 16 color palette. If the image contains a color that is not in the standard palette, ppmtopcx fails. The standard palette is not only a set of colors, but a specific mapping of palette indexes to colors. E.g. red is 4. You can use pnmremap with a suitable PPM image of the standard palette to adapt your image to use exactly those colors in the palette so that ppmtopcx -stdpalette will work on it. The file pcxstd.ppm, part of Netpbm, contains the standard palette. Although the PCX header tells exactly what palette is used in the file, some older PCX interpreters do not use that information. They instead assume the standard palette. If you don't use the -stdpalette option, ppmtopcx, ppmtopcx may create an image that uses a different palette (a rearrangement of the same colors) and then one of these older interpreters would interpret the colors in the image wrong. You cannot specify this option along with -palette. This option was new in Netpbm 10.22 (April 2004). -palette=palettefile Instead of computing the palette from the colors in the image, use the palette from the file palettefile. If the palette contains a color that is not in that palette, ppmtopcx fails. The palette file must be a PPM image that contains one pixel for each color in the palette. It doesn't matter what the aspect ratio of the palette image is. The order of the colors in the PCX palette is the order of the pixels in the PPM image in standard western reading order (left to right, top to bottom). If there is a duplicate color in the palette, ppmtopcx chooses between them arbitrarily in building the PCX raster. You would need this only if you have a PCX reader that can't read the palette that is in the PCX file and instead assumes some particular palette. See also the -stdpalette option. If your input image might contain colors other than those in your palette, you can convert the input image to one that contains only those colors in your palette with pnmremap. You cannot specify this along with -stdpalette. This option was new in Netpbhm 10.25 (October 2004). -planes=planes Generate a PCX file with planes planes, even though the number of colors in the image could be represented in fewer. This makes the file larger, but some PCX interpreters are capable of processing only certain numbers of planes. This is meaningful only when ppmtopcx generates an image in the 16 color palette format without packed pixels. Consequently, you cannot specify this option together with -24bit or -8bit or -packed. The valid values for planes are 1, 2, 3, and 4. By default, ppmtopcx chooses the smallest number of planes that can represent the colors in the image. E.g. if there are 5 colors, ppmtopcx chooses 3 planes. This option was new in Netpbm 10.21 (March 2004). -xpos=cols -ypos=rows These options set the position of the image in some field (e.g. on a screen) in columns to the right of the left edge and rows below the top edge. The PCX format contains image position information. Don't confuse this with the position of an area of interest within the image. For example, using pnmpad to add a 10 pixel left border to an image and then converting that image to PCX with xpos = 0 is not the same as converting the original image to PCX and setting xpos = 10. The values may be from -32767 to 32768. The default for each is zero. SEE ALSO pcxtoppm, ppm AUTHORS Copyright (C) 1994 by Ingo Wilken (Ingo.Wilken@informatik.uni-oldenburg.de) Based on previous work by Michael Davidson. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO AUTHORS øppmmake Updated: 02 September 2002 Table Of Contents NAME ppmmake - create a PPM image of a specified color and dimensions SYNOPSIS ppmmake -maxval=maxval color width height All options can be abbreviated to their shortest unique prefix. You may use two hyphens instead of one to designate an option. You may use either white space or an equals sign between an option name and its value. DESCRIPTION This program is part of Netpbm. ppmmake produces a PPM image of the specified color, width, height, and maxval. Specify the color (color) as described for the argument of the ppm_parsecolor() library routine. EXAMPLES ppmmake red 50 50 ppmmake rgb:ff/80/80 50 100 -maxval=5 OPTIONS -maxval=maxval The maxval for the generated image. Default is 255. This option did not exist before June 2002. Before, the maxval was always 255. SEE ALSO pbmmake, ppmpat, ppm AUTHOR Copyright (C) 1991 by Jef Poskanzer. Table Of Contents NAME SYNOPSIS DESCRIPTION EXAMPLES OPTIONS AUTHOR øppmmake Updated: 02 September 2002 Table Of Contents NAME ppmmake - create a PPM image of a specified color and dimensions SYNOPSIS ppmmake -maxval=maxval color width height All options can be abbreviated to their shortest unique prefix. You may use two hyphens instead of one to designate an option. You may use either white space or an equals sign between an option name and its value. DESCRIPTION This program is part of Netpbm. ppmmake produces a PPM image of the specified color, width, height, and maxval. Specify the color (color) as described for the argument of the ppm_parsecolor() library routine. EXAMPLES ppmmake red 50 50 ppmmake rgb:ff/80/80 50 100 -maxval=5 OPTIONS -maxval=maxval The maxval for the generated image. Default is 255. This option did not exist before June 2002. Before, the maxval was always 255. SEE ALSO pbmmake, ppmpat, ppm AUTHOR Copyright (C) 1991 by Jef Poskanzer. Table Of Contents NAME SYNOPSIS DESCRIPTION EXAMPLES OPTIONS AUTHOR øppmpat Updated: 12 June 2004 Table Of Contents NAME ppmpat - make a pretty PPM image SYNOPSIS ppmpat {-gingham2|-g2} | {-gingham3|-g3} | -madras | -tartan | -poles | -squig | -camo | -anticamo width height You can abbreviate any option to its shortest unique prefix. DESCRIPTION This program is part of Netpbm. ppmpat produces a PPM 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 routines. Still, some of the patterns can be rather pretty. If you have a color workstation, something like ppmpat -squig 300 300 | pnmquant 128 should generate a nice background. Some of these patterns have large numbers of colors, so if you want a simpler pattern, use pnmquant on the output. OPTIONS The options specify various 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. -squig Squiggley tubular pattern. Can be tiled. -camo Camouflage pattern. -anticamo Anti-camouflage pattern - like -camo, but ultra-bright colors. REFERENCES Some of the patterns are from "Designer's Guide to Color 3" by Jeanne Allen. SEE ALSO pnmtile, pnmquant, ppmmake, ppmrainbow, ppm AUTHOR Copyright (C) 1989 by Jef Poskanzer. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS REFERENCES SEE ALSO AUTHOR øppmrainbow Updated: 1 July 2001 Table Of Contents NAME ppmrainbow - Generate a rainbow SYNOPSIS ppmrainbow [-width=number] [-height=number] [-tmpdir=directory] [-norepeat] [-verbose] color ... All options can be abbreviated to their shortest unique prefix. You may use two hyphens instead of one to designate an option. You may use either white space or equals signs between an option name and its value. DESCRIPTION This program is part of Netpbm. ppmrainbow generates a PPM image that fades from one color to another to another from left to right, like a rainbow. The colors are those you specify on the command line, in that order. The first color is added again on the right end of the image unless you specify the -norepeat option. If you want a vertical or other non-horizontal rainbow, run the output through pnmrotate or pamflip. One use for such a rainbow is to compose it with another image under an alpha mask in order to add a rainbow area to another image. In fact, you can make rainbow-colored text by using pbmtext, pamcomp, and ppmrainbow. OPTIONS -width number The width in pixels of the output image. Default is 600. -height number The height in pixels of the output image. Default is 8. -norepeat This option makes ppmrainbow end the rainbow with the last color you specify. Without this option, ppmrainbow adds the first color you specify to the right end of the rainbow as if you had repeated it. (I don't understand the point of this default behavior; it exists today just for backward compatibility). -tmpdir The directory specification of the directory ppmrainbow is to use for temporary files. Default is the value of the TMPDIR environment variable, or /tmp if TMPDIR is not set. -verbose Print the "commands" (invocations of other Netpbm programs) that ppmrainbow uses to create the image. SEE ALSO ppmmake, pamcomp, pbmtext, ppmfade, pnmrotate, pamflip, ppm. AUTHOR Arjen Bax wrote ppmrainbow in June 2001 and contributed it to the Netpbm package. Bryan Henderson wrote this manual in July 2001. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO AUTHOR øppmrough Updated: 23 August 2002 Table Of Contents NAME ppmrough - create PPM image of two colors with a ragged border between them SYNOPSIS ppmrough [-left pixels] [-right pixels] [-top pixels] [-bottom pixels] [-width pixels] [-height pixels] [-bg rgb:##/##/##] [-fg rgb:##/##/##] [-var pixels] [-init seed] [-verbose] All options can be abbreviated to their shortest unique prefix. You may use two hyphens instead of one. You may separate an option name and its value with white space instead of an equals sign. DESCRIPTION This program is part of Netpbm. ppmrough generates a PPM image of the specified width, height, and colors. ppmrough tiles the image into semi-rectangular regions with a ragged borders between them. It calculates the fluctuations with the rand() standard C library function. ppmrough writes the PPM image to Standard Output. The maxval of the output image is 255 (You can change this with pnmdepth). Use the options -left or -right, respectively, to make vertical borders, and -top or -bottom, respectively, to generate horizontal borders inside the image. Each of these options needs an integer value pixels that determines the average distance of the interior border to the related edge of the image. You may combine the -left, -right, -top, and -bottom options to generate an image with more than one border. The algorithm ensures that you can concatenate two images produced with the same (i.e. -left) value without dislocations. You specify the dimensions of the generated image with the -width and -height options. Use the -bg and -fg options to set the background (margin) color and the foreground (interior) color, respectively. If you don't specify any of the -left, -right, -top, and -bottom options, all pixels are set to foreground color. The defaults are white foreground and black background. Use the -var option to control the "raggedness" of the border. The less its value is the smoother the border is. You can initialize the pseudo-random generator with the -init option. You could use ppmrough with ppmtopgm to create a PGM alpha mask and use it to roughen up the edges of another image. OPTIONS -left pixels Specifies the mean distance of the border from the left margin (default: no border). -right pixels Specifies the mean distance of the border from the right margin (default: no border). -top pixels Specifies the mean distance of the border from the top margin (default: no border). -bottom pixels Specifies the mean distance of the border from the bottom margin (default: no border). -width pixels Specifies the width of the image (default: 100). -height pixels Specifies the height of the image (default: 100). -bg color Background color. Specify this the same way you specify a color with ppmmake. Default is black. -fg color Foreground color. Specify this the same way you specify a color with ppmmake. Default is white. -var pixels Specifies the variance of the ragged border (default: 10). Must be a positive integer. Set pixels to 1 to get a straight border. -init seed Use this option to initialize the pseudo-random number generator (the Standard C library rand() function) with seed. -verbose Run ppmrough in verbose mode. It reports all parameters on Standard Error. SEE ALSO ppmmake, pnmcat, ppmtopgm, ppm, HISTORY This program was added to Netpbm in Release 10.9 (September 2002). AUTHOR Copyright (C) 2002 by Eckard Specht. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO AUTHOR øpgmnoise Updated: 16 November 1993 Table Of Contents NAME pgmnoise - create a graymap made up of white noise SYNOPSIS pgmnoise width height DESCRIPTION This program is part of Netpbm. pgmnoise creates a portable graymap that is made up of random pixels with gray values in the range of 0 to PGM_MAXMAXVAL (depends on the compilation, either 255 or 65535). The graymap has a size of width * height pixels. SEE ALSO pgm AUTHOR Copyright (C) 1993 by Frank Neumann Table Of Contents NAME SYNOPSIS DESCRIPTION SEE ALSO AUTHOR øpbmtext Updated: 22 April 2003 Table Of Contents NAME pbmtext - render text into a PBM image SYNOPSIS pbmtext [-font fontfile] [-builtin fontname] [-space pixels] [-lspace pixels] [-nomargins] [-width pixels] [text] Minimum unique abbreviation of option is acceptable. You may use double hyphens instead of single hyphen to denote options. You may use white space in place of the equals sign to separate an option name from its value. DESCRIPTION This program is part of Netpbm. pbmtext takes the specified text, either a single line from the command line or multiple lines from standard input, and renders it into a PBM graphical image. In the image, each line of input is a line of output. Formatting characters such as newline have no effect on the formatting; like any unprintable character, they turn into spaces. The image is just wide enough for the longest line of text, plus margins, and just high enough to contain the lines of text, plus margins. The left and right margins are twice the width of the widest character in the font; the top and bottom margins are the height of the tallest character in the font. But if the text is only one line, all the margins are half of this. You can use the -nomargins option to eliminate the margins. pbmtextps does the same thing as pbmtext, but uses Ghostscript to generate the characters, which means it's a lot more sophisticated and you can use Postscript fonts. But it also means you have to have Ghostscript installed and it isn't as fast. OPTIONS -font,-builtin By default, pbmtext uses a built-in font called bdf (about a 10 point Times-Roman font). You can use a fixed width font by specifying -builtin fixed. You can also specify your own font with the -font option. The fontfile is either a BDF file from the X window system or a PBM file. If the fontfile is a PBM file, it is 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 pamcut to remove everything except the text. Finally, run it through pnmcrop. to make sure the edges are right up against the text. pbmtext can figure out the sizes and spacings from that. -space pixels Add pixels pixels of space between characters. This is in addition to whatever space surrounding characters is built into the font, which is usually enough to produce a reasonable string of text. pixels may be fractional, in which case the number of pixels added varies so as to achieve the specified average. For example -space=1.5 causes half the spaces to be 1 pixel and half to be 2 pixels. pixels may be negative to crowd text together, but the author has not put much thought or testing into how this works in every possible case, so it might cause disastrous results. -lspace pixels Add pixels pixels of space between lines. This is in addition to whatever space above and below characters is built into the font, which is usually enough to produce a reasonable line spacing. pixels must be a whole number. pixels may be negative to crowd lines together, but the author has not put much thought or testing into how this works in every possible case, so it might cause disastrous results. -nomargins By default, pbmtext adds margins all around the image as described above. This option causes pbmtext not to add any margins. Note that there may still be space beyond the edges of the type because a character itself may include space at its edges. To eliminate all surrounding background, so the type touches all four edges of the image, use pnmcrop. -width pixels This specifies how much horizontal space the text is supposed to fit into. If the input is one line, pbmtext breaks it into multiple lines as needed to fit the specified width. It breaks it between characters, but does not pay attention to white space; it may break in the middle of a word and a line may begin or end with white space. If the input is multiple lines, pbmtext assumes you already have line breaks where they make sense, and pbmtext simply truncates each line as needed to fit the specified width. USAGE Often, you want to place text over another image. One way to do this is with ppmlabel. ppmlabel does not give you the font options that pbmtext does, though. Another way is to use pbmtext to create an image containing the text, then use pamcomp to overlay the text image onto your base image. To make only the text (and not the entire rectangle containing it) cover the base image, you will need to give pamcomp a mask, via its -alpha option. You can just use the text image itself as the mask, as long as you also specify the -invert option to pamcomp. If you want to overlay colored text instead of black, just use ppmchange to change all black pixels to the color of your choice before overlaying the text image. But still use the original black and white image for the alpha mask. If you want the text at an angle, use pnmrotate on the text image (and alpha mask) before overlaying. SEE ALSO pbmtextps, pamcut, pnmcrop, pamcomp, ppmchange, pnmrotate, ppmlabel, pstopnm, pbm AUTHOR Copyright (C) 1993 by Jef Poskanzer and George Phillips Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS USAGE SEE ALSO AUTHOR øpbmtext Updated: 22 April 2003 Table Of Contents NAME pbmtext - render text into a PBM image SYNOPSIS pbmtext [-font fontfile] [-builtin fontname] [-space pixels] [-lspace pixels] [-nomargins] [-width pixels] [text] Minimum unique abbreviation of option is acceptable. You may use double hyphens instead of single hyphen to denote options. You may use white space in place of the equals sign to separate an option name from its value. DESCRIPTION This program is part of Netpbm. pbmtext takes the specified text, either a single line from the command line or multiple lines from standard input, and renders it into a PBM graphical image. In the image, each line of input is a line of output. Formatting characters such as newline have no effect on the formatting; like any unprintable character, they turn into spaces. The image is just wide enough for the longest line of text, plus margins, and just high enough to contain the lines of text, plus margins. The left and right margins are twice the width of the widest character in the font; the top and bottom margins are the height of the tallest character in the font. But if the text is only one line, all the margins are half of this. You can use the -nomargins option to eliminate the margins. pbmtextps does the same thing as pbmtext, but uses Ghostscript to generate the characters, which means it's a lot more sophisticated and you can use Postscript fonts. But it also means you have to have Ghostscript installed and it isn't as fast. OPTIONS -font,-builtin By default, pbmtext uses a built-in font called bdf (about a 10 point Times-Roman font). You can use a fixed width font by specifying -builtin fixed. You can also specify your own font with the -font option. The fontfile is either a BDF file from the X window system or a PBM file. If the fontfile is a PBM file, it is 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 pamcut to remove everything except the text. Finally, run it through pnmcrop. to make sure the edges are right up against the text. pbmtext can figure out the sizes and spacings from that. -space pixels Add pixels pixels of space between characters. This is in addition to whatever space surrounding characters is built into the font, which is usually enough to produce a reasonable string of text. pixels may be fractional, in which case the number of pixels added varies so as to achieve the specified average. For example -space=1.5 causes half the spaces to be 1 pixel and half to be 2 pixels. pixels may be negative to crowd text together, but the author has not put much thought or testing into how this works in every possible case, so it might cause disastrous results. -lspace pixels Add pixels pixels of space between lines. This is in addition to whatever space above and below characters is built into the font, which is usually enough to produce a reasonable line spacing. pixels must be a whole number. pixels may be negative to crowd lines together, but the author has not put much thought or testing into how this works in every possible case, so it might cause disastrous results. -nomargins By default, pbmtext adds margins all around the image as described above. This option causes pbmtext not to add any margins. Note that there may still be space beyond the edges of the type because a character itself may include space at its edges. To eliminate all surrounding background, so the type touches all four edges of the image, use pnmcrop. -width pixels This specifies how much horizontal space the text is supposed to fit into. If the input is one line, pbmtext breaks it into multiple lines as needed to fit the specified width. It breaks it between characters, but does not pay attention to white space; it may break in the middle of a word and a line may begin or end with white space. If the input is multiple lines, pbmtext assumes you already have line breaks where they make sense, and pbmtext simply truncates each line as needed to fit the specified width. USAGE Often, you want to place text over another image. One way to do this is with ppmlabel. ppmlabel does not give you the font options that pbmtext does, though. Another way is to use pbmtext to create an image containing the text, then use pamcomp to overlay the text image onto your base image. To make only the text (and not the entire rectangle containing it) cover the base image, you will need to give pamcomp a mask, via its -alpha option. You can just use the text image itself as the mask, as long as you also specify the -invert option to pamcomp. If you want to overlay colored text instead of black, just use ppmchange to change all black pixels to the color of your choice before overlaying the text image. But still use the original black and white image for the alpha mask. If you want the text at an angle, use pnmrotate on the text image (and alpha mask) before overlaying. SEE ALSO pbmtextps, pamcut, pnmcrop, pamcomp, ppmchange, pnmrotate, ppmlabel, pstopnm, pbm AUTHOR Copyright (C) 1993 by Jef Poskanzer and George Phillips Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS USAGE SEE ALSO AUTHOR øpbmupc Updated: 14 March 1989 Table Of Contents NAME pbmupc - create a Universal Product Code PBM image SYNOPSIS pbmupc [-s1 | -s2] type manufacturer product DESCRIPTION This program is part of Netpbm. pbmupc generates an image of a Universal Product Code symbol. The three arguments are: a one digit product type, a five digit manufacturer code, and a five digit product code. For example, "0 72890 00011" is the code for Heineken. As presently configured, pbmupc produces an image 230 bits wide and 175 bits high. The size can be altered by changing the defines at the beginning of the program, or by running the output through pnmenlarge or pnmscale. OPTIONS The -s1 and -s2 options select the style of UPC to generate. The default, -s1, looks more or less like this: |||||||||||||||| |||||||||||||||| |||||||||||||||| |||||||||||||||| 0||12345||67890||5 The other style, -s2, puts the product type digit higher up, and doesn't display the checksum digit: |||||||||||||||| |||||||||||||||| 0|||||||||||||||| |||||||||||||||| ||12345||67890|| SEE ALSO pbm AUTHOR Copyright (C) 1989 by Jef Poskanzer. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO AUTHOR øpamstereogram Updated: 18 April 2004 Table Of Contents NAME pamstereogram - create a PAM single-image stereogram from a PAM height map SYNOPSIS pamstereogram [-help] [-verbose] [-pbm | -pgm | -ppm] [-maxval value] [-patfile pnmfile] [-pam] [-xshift pixels] [-yshift pixels] [-magnifypat scale] [-guidesize pixels] [-dpi resolution] [-crosseyed] [-makemask] [-eyesep inches] [-depth fraction] [infile] Minimum unique abbreviation of option is acceptable. You may use double hypens instead of single hyphen to denote options. You may use white space in place of the equals sign to separate an option name from its value. DESCRIPTION This program is part of Netpbm. pamstereogram inputs a height map (a map of the distances from your eye of the points in a scene) and outputs a single-image stereogram (SIS). A SIS is a 2-D image specially designed to appear three dimensional when viewed with relaxed, slightly unfocused eyes. What's exciting about single-image stereograms is that they don't require special glasses to view, although it does require a bit of practice to train your eyes to unfocus properly. pamstereogram program provides a wealth of control over how the stereogram is generated, including the following: black and white, grayscale, or color output single-image random-dot stereograms (SIRDS) or single-image stereograms (SIS) using a tiled image images targeting a given device resolution and eye separation optional guide boxes to assist in focusing the ability to trade off depth levels for easier viewing choice of ordinary or cross-eyed stereograms The output is a PAM image on Standard Output. Options control the exact format of the PAM. If you want a PNM (PBM, PGM, or PPM) image, use pamtopnm on the output. To make a red/green type of stereogram (that you view with 3-D glasses) instead, see ppm3dx OPTIONS -verbose Display messages about image sizes and formats and properties of the stereogram being generated. -blackandwhite Produce a single-image random-dot black and white stereogram. This is the default. -grayscale Produce a single-image random-dot grayscale stereogram. -color Produce a single-image random-dot color stereogram. -maxval=value Designate the maximum value of each gray/color component, i.e. the color resolution. Smaller values make the output image have smaller numbers of unique grays/colors. If you don't specify -maxval, pamstereogram uses the maxval of the input image. This option has no effect with -blackandwhite. -patfile=pnmfile Specify an image to use as a repeated background pattern for the stereogram instead of a random-dot pattern. Intricate images generally produce a crisper 3-D effect that simpler images. The output file will have the same maxval and format (black and white, grayscale or color) as the pattern file. You cannot specify the -patfile option along with -blackandwhite, -grayscale, -color, or -maxval. -xshift=pixels Shift the pattern image (designated by -patfile) to the right by pixels pixels (default: 0). -xshift is helpful when creating "true-color" stereograms. This option is valid only along with -patfile. -yshift pixels Shift the pattern image (designated by -patfile) downwards by pixels pixels (default: 0). This option is valid only along with -patfile. -magnifypat=scale Magnify each pixel in the pattern file or each random dot by integral scaling factor scale. Note that pamstereogram applies the pattern magnification after pattern shifting (-xshift and -yshift). -guidesize=pixels Draw a pair of pixels by pixels black squares on a white background underneath the stereogram proper. These squares help you guide your eyes into proper focus to view the 3-D image. The trick is to focus your eyes some distance behind the image, causing you to see four black squares, then continue altering your focus distance until the middle two black squares fuse into a single black square. At that point, a crisp, 3-D image will appear. If pixels is negative, pamstereogram will draw the guide squares above the stereogram instead of below it. If pixels is zero (the default), pamstereogram will draw no guide squares. -dpi=resolution Specify the resolution of the output device in dots per inch. The default is 96 DPI, which represents a fairly crisp screen resolution. -crosseyed Invert the gray levels in the height map (input image) so that the 3-D image pops out of the page where it would otherwise sink into the page and vice versa. Some people are unable to diverge their eyes and can only cross them. The -crosseyed option enables such people to see the 3-D image as intended. -makemask Instead of a stereogram, output a PAM mask image showing coloring constraints. New pixels will be taken from the pattern file where the mask is black. Copies of existing pixels will be taken from the pattern file where the mask is white. The -makemask option can be used to help create more sophisticated pattern files (to use with -patfile) Note that -makemask ignores -magnifypat; it always produces masks that assume a pattern magnification of 1. -eyesep=inches Specify the separation in inches between your eyes. The default, 2.5 inches (6.4 cm), should be sufficient for most people and probably doesn't need to be changed. -depth=fraction Specify the output image's depth of field. That is, fraction represents the fractional distance of the near plane from the far plane. Smaller numbers make the 3-D image easier to perceive but flatter. Larger numbers make the 3-D image more difficult to perceive but deeper. The default, 0.3333, generally works fairly well. PARAMETERS The only parameter, infile, is the name of an input file that is a height map image. If you don't specify infile, the input is from Standard Input. The input is a PAM image of depth 1. Each sample represents the distance from the eye that the 3-D image at that location should be. Higher numbers mean further from the eye. pamstereogram pays no attention the the image's tuple type and ignores all planes other than Plane 0. Like any Netpbm program, pamstereogram will accept PNM input as if it were the PAM equivalent. A good initial test is to input an image consisting of a solid image of distance 0 within a large field of maximum distance. EXAMPLES Generate a SIRDS out of small, brightly colored squares and prepare it for display on an 87 DPI monitor: pamstereogram heightmap.pam \ -dpi 87 -verbose -color -maxval 1 -magnifypat 3 \ >3d.pam Generate a SIS by tiling a PPM file (a prior run with -verbose indicates how wide the pattern file should be for seamless tiling, although any width is acceptable for producing SISes): pamstereogram myheights.pam -patfile mypattern.ppm >mysis.pam SEE ALSO pam ppm3d Harold W. Thimbleby, Stuart Inglis, and Ian H. Witten. Displaying 3D Images: Algorithms for Single Image Random Dot Stereograms. In IEEE Computer, 27(10):38-48, October 1994. HISTORY pamstereogram was new in Netpbm 10.22 (April 2004). AUTHOR Copyright (C) 2004 Scott Pakin, scott+pbm@pakin.org. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS PARAMETERS EXAMPLES SEE ALSO HISTORY AUTHOR øppmwheel Updated: 11 January 2003 Table Of Contents NAME ppmwheel - make a PPM image of a color wheel SYNOPSIS ppmwheel diameter DESCRIPTION This program is part of Netpbm. ppmwheel produces a PPM image of a color wheel of the specified diameter inside a white square just large enough to hold it. The color wheel is based on the HSV color model. Hues are distributed angularly around the circle and the values are distributed radially and the saturation is zero everywhere. The values are zero at the center, increasing linearly to maximum at the edge. The maximum value corresponds to the maxval of the PPM image. Hence, the image contains all of the secondary colors based on the red, green, and blue primary colors. A secondary color is one that is composed of light of at most two of the three primary colors. OPTIONS None. SEE ALSO ppmcie, ppmrainbow, ppm HISTORY ppmwheel was added to Netpbm in Release 10.14 (March 2003). AUTHOR Copyright (C) 1995 by Peter Kirchgessner Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO HISTORY AUTHOR øPPMCIE Updated: 26th September 1994 Table Of Contents NAME ppmcie - draw a CIE color chart as a PPM image SYNOPSIS ppmcie [ -rec709|-cie|-ebu|-hdtv|-ntsc|-smpte ] [-xy|-upvp] [-red rx ry] [-green gx gy] [-blue bx by] [-white wx wy] [-size edge] [{-xsize|-width} width] [{-ysize|-height} height] [-noblack] [-nowpoint] [-nolabel] [-noaxes] [-full] You may abbreviate any option to its shortest unique prefix. DESCRIPTION This program is part of Netpbm. ppmcie creates a PPM file containing a plot of the CIE "tongue" color chart -- to the extent possible in a PPM image. Alternatively, creates a pseudo-PPM image of the color tongue using RGB values from a color system of your choice. The CIE color tongue is an image of all the hues that can be described by CIE X-Y chromaticity coordinates. They are arranged on a two dimensional coordinate plane with the X chromaticity on the horizontal axis and the Y chromaticity on the vertical scale. (You can choose alternatively to use CIE u'-v' chromaticity coordinates, but the general idea of the color tongue is the same). Note that the PPM format specifies that the RGB values in the file are from CIE Rec. 709 color system, gamma-corrected. And positive. See ppm for details. If you use one of the color system options on ppmcie, what you get is not a true PPM image, but is very similar. If you display such ppmcie output using a device that expects PPM input (which includes just about any computer graphics display program), it will display the wrong colors. However, you may have a device that expects one of these variations on PPM. In every RGB color system you can specify, including the default (which produces a true PPM image) there are hues in the color tongue that can't be represented. For example, monochromatic blue-green with a wavelength of 500nm cannot be represented in a PPM image. For these hues, ppmcie substitutes a similar hue as follows: They are desaturated and rendered as the shade where the edge of the Maxwell triangle intersects a line drawn from the requested shade to the white point defined by the color system's white point. Furthermore, unless you specify the -full option, ppmcie reduces their intensity by 25% compared to the true hues in the image. ppmcie draws and labels the CIE X-Y coordinate axes unless you choose otherwise with options. ppmcie draws the Maxwell triangle for the color system in use on the color tongue. The Maxwell triangle is the triangle whose vertices are the primary illuminant hues for the color system. The hues inside the triangle show the color gamut for the color system. They are also the only ones that are correct for the CIE X-Y chromaticity coordinates shown. (See explanation above). ppmcie also places a mark at the color system's white point and displays in text the CIE X-Y chromaticities of the primary illuminants and white point for the color system. You can turn this off with options, though. ppmcie annotates the periphery of the color tongue with the wavelength, in nanometers of the monochromatic hues which appear there. Finally, ppmcie displays the black body chromaticity curve for Planckian radiators from 1000 to 30000 kelvins on the image. You can choose from several standard color systems, or specify one of your own numerically. CIE charts, by their very nature, contain a very large number of colors. If you're encoding the chart for a color mapped device or file format, you'll need to use pnmquant or ppmdither to reduce the number of colors in the image. OPTIONS -rec709 -cie -ebu -hdtv -ntsc -smpte Select a standard color system whose gamut to plot. The default is -rec709, which chooses CIE Rec. 709, gamma-corrected. This is the only color system for which ppmcie's output is a true PPM image. See explanation above. -ebu chooses the primaries used in the PAL and SECAM broadcasting standards. -ntsc chooses the primaries specified by the NTSC broadcasting system (few modern monitors actually cover this range). -smpte selects the primaries recommended by the Society of Motion Picture and Television Engineers (SMPTE) in standards RP-37 and RP-145, and -hdtv uses the much broader HDTV ideal primaries. -cie chooses a color system that has the largest possible gamut within the spectrum of the chart. This is the same color system as you get with the -cie option to John Walker's cietoppm program. -xy plot CIE 1931 x y chromaticities. This is the default. -upvp plot u' v' 1976 chromaticities rather than CIE 1931 x y chromaticities. The advantage of u' v' coordinates is that equal intervals of distance on the u' v' plane correspond roughly to the eye's ability to discriminate colors. -red rx ry specifies the CIE x and y co-ordinates of the red illuminant of a custom color system and selects the custom system. -green gx gy specifies the CIE x and y co-ordinates of the green illuminant of the color system and selects the custom system. -blue bx by specifies the CIE x and y co-ordinates of the blue illuminant of the color system and selects the custom system. -white wx wy specifies the CIE x and y co-ordinates of the white point of the color system and selects the custom system. -size edge Create a pixmap of edge by edge pixels. The default is 512x512. -xsize|-width width Sets the width of the generated image to width pixels. The default width is 512 pixels. If the height and width of the image are not the same, the CIE diagram will be stretched in the longer dimension. -ysize|-height height Sets the height of the generated image to height pixels. The default height is 512 pixels. If the height and width of the image are not the same, the CIE diagram will be stretched in the longer dimension. -noblack Don't plot the black body chromaticity curve. -nowpoint Don't plot the color system's white point. -nolabel Omit the label. -noaxes Don't plot axes. -full Plot the entire CIE tongue in full intensity; don't enhance the gamut of the specified color system. SEE ALSO ppmdither, pnmquant, ppm AUTHOR Copyright (C) 1995 by John Walker (kelvin@fourmilab.ch) WWW home page: http://www.fourmilab.ch/ Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, without any conditions or restrictions. This software is provided as is without express or implied warranty. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO AUTHOR øpbmpage Updated: 01 May 2000 Table Of Contents NAME pbmpage - create a one page test pattern for printing SYNOPSIS pbmpage [-a4] test_pattern DESCRIPTION This program is part of Netpbm. pbmpage generates a one page test pattern to print on a sheet of paper, for use in calibrating a printer. The test pattern in is PBM format. pbmpage produces an image intended for 600 dots per inch printer resolution. If you are printing on an HP PPA printer, you can convert the output of this program to a stream that you can feed to the printer with pbmtoppa. Bear in mind that when you print the test pattern, you are testing not only the printer, but any converter or driver software along the printing path. Any one of these components may adjust margins, crop the image, erase edges, and such. If, due to addition of margins, the printer refuses to print the image because it is too big, use pamcut to cut the right and bottom edges off the test pattern until it is small enough to print. test_pattern is the number of the test pattern to generate, as follows. The default is 1. 1 A black on white grid ruled in numbers of pixels. A black one pixel box is at the very edges of the paper. Before Netpbm 10.18 (August 2003), the perimeter box was not there. 2 A vertical line segment, one pixel wide, extending 1/2" up from the exact center of the page. 3 Two diagonal line segments, one starting at the upper left corner of the page, the other starting from the lower left corner of the page. Both extend 1/2" toward the center of the page at 45 degrees. OPTIONS -a4 Generate an image for A4 (European) paper. Without this option, pbmpage generates an image for US standard paper (8 1/2" wide x 11" high). SEE ALSO pbmtoppa, pamcut, pbm AUTHOR Tim Norman. Copyright (C) 1998. Licensed under GNU Public License Manual page by Bryan Henderson, May 2000. Contributed to the public domain by its author. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO AUTHOR øpamseq Updated: 8 May 2002 Table Of Contents NAME pamseq - generate PAM image of all possible tuple values, in sequence SYNOPSIS pamseq [-tupletype tupletype] depth maxval All options can be abbreviated to their shortest unique prefix. You may use two hyphens instead of one to designate an option. You may use either white space or an equals sign between an option name and its value. DESCRIPTION This program is part of Netpbm. pamseq generates a PAM image of a specified depth and specified maxval that consists of a single row. The row consists of one tuple of every possible value, in order. For a depth of one, the order is simple: From 0 to maxval, going from left to right. For higher depths, the highest numbered plane goes from 0 to maxval (going left to right) while all the other planes have value 0. Then the sequence repeats except with the next highest plane set to a value of 1, then 2, etc. OPTIONS -tupletype This is the value of the "tuple_type" attribute of the created PAM image. It can be any string up to 255 characters. USAGE To create a simple ramp of the values 0..255, for input to various matrix calculations, try pamseq 1 255 (Before pamseq existed, pgmramp was often pressed into service for this). To create a PPM color map of all the possible colors representable with a maxval of 5, do pamseq 3 5 -tupletype=RGB | pamtopnm Again, with a modern program based on the Netpbm library, you don't need the pamtopnm because a PAM RGB image is equivalent to a PPM image. You can use such a color map with pnmremap to quantize the colors in an image. With the maxval of 5 given in the example, you get a color map of the set of "web safe" colors as defined by Netscape. Most web browsers guarantee that they can produce at least these 216 colors (215 plus black). SEE ALSO pnmremap, pamtopnm, pam HISTORY pamseq was added to Netpbm in June 2002. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS USAGE SEE ALSO HISTORY øpamgauss Updated: 8 May 2004 Table Of Contents NAME pamgauss - create a two dimensional gaussian function as a PAM image SYNOPSIS pamgauss -width -height -sigma=number [-maxval=number] [-tupletype=string] Minimum unique abbreviation of option is acceptable. You may use double hyphens instead of single hyphen to denote options. You may use white space in place of the equals sign to separate an option name from its value. EXAMPLES pamgauss 3 3 -sigma=.5 -tupletype=GRAYSCALE | pamtopnm >gauss.pgm pnmconvol -nooffset gauss.pgm myimage.ppm >blurred.ppm DESCRIPTION This program is part of Netpbm. pamgauss generates a one-plane PAM image whose samples are a gaussian function of their distance from the center of the image. I.e. the sample value is highest in the center and goes down, in a bell curve shape, as you move away from the center. The values are scaled so that the area under the surface of the two-dimensional Gaussian function is the maxval of the image. You can use this image, converted to PGM, as a convolution kernel with pnmconvol to blur an image. (This technique is known as Gaussian blurring). width and height are the dimensions of the image that pamgauss generates. Mathematically speaking, they are the domain of the two dimensional gaussian function. The sum of all the samples is equal to the image's maxval (within rounding error). This is true even if you clip the Gaussian function by making the image too small. If you want to be sure you get a whole Gaussian function, make sure that you choose a sigma and image dimensions so that if you made it any larger, the sample values at the edges would be zero. The output image is PAM. To turn it into a PGM that you can use with pnmconvol, specify -tupletype=GRAYSCALE and pass the output through pamtopnm. You must use the -nooffset option on pnmconvol because zero means zero in the PAM that pamgauss generates. DESCRIPTION This program is part of Netpbm. -sigma=number This is the sigma parameter of the Gaussian function (if it were a Gaussian probability function, this would be its the standard deviation). The higher the number, the more spread out the function is. Normally, you want to make this number low enough that the function reaches zero value before the edge of your image. number is in units of pixels. This option is required. There is no default. -maxval=number This is the maxval for the output image. It defaults to 255. -tupletype=string This is the value of the "tuple_type" attribute of the created PAM image. It can be any string up to 255 characters. If you don't specify this, pamgauss generates a PAM with unspecified tuple type. SEE ALSO pnmconvol, pamtopnm, pgmkernel, pamseq, pam HISTORY pamgauss was new in Netpbm 10.23 (July 2004). Table Of Contents NAME SYNOPSIS SYNOPSIS DESCRIPTION SEE ALSO AUTHORS øppmlabel Updated: 12 September 2003 Table Of Contents NAME ppmlabel - add text to a PPM image SYNOPSIS ppmlabel [-angle angle] [-background { transparent | color } ] [-color color] [-file filename] [-size textsize] [-text text_string] [-x column] [-y row] ... [ppmfile] DESCRIPTION This program is part of Netpbm. ppmlabel uses the text drawing facilities of ppmdraw to add text to a PBM image. You control the location, size, baseline angle, color of the text, and background color (if any) with command line arguments. You can specify the text on the command line or supply it in files. You can add any number of separate labels in a single invocation of ppmlabel, limited only by any restrictions your environment has on the number and size of program arguments (e.g. a shell's command size limit). If you don't specify ppmfile, ppmdraw reads its input PPM image from Standard Input. The output image goes to Standard Output. A more sophisticated way to add a label to an image is to use pbmtext or pbmtextps to create an image of the text, then pamcomp to overlay it onto the base image. OPTIONS The arguments on the ppmlabel command line are not options in the strict sense; they are commands which control the placement and appearance of the text being added to the input pixmap. They are executed left to right, and any number of arguments may appear. You can abbreviate any "option" to its shortest unique prefix. -angle angle This option sets the angle of the baseline of subsequent text. angle is an integral number of degrees, measured counterclockwise from the row axis of the image. -background { transparent | color } If the argument is transparent, ppmlabel draws the text over the existing pixels in the pixmap. If you specify a color (see the -color option below for information on how to specify colors), ppmlabel generates background rectangles enclosing subsequent text, and those rectangles are filled with that color. -color color This option sets the color for subsequent text. Specify the color (color) as described for the argument of the ppm_parsecolor() library routine. -colour is an acceptable alternate spelling. -file filename This option causes ppmlabel to read lines of text from the file named filename and draw it on successive lines. -size textsize This option sets the height of the tallest characters above the baseline to textsize pixels. -text text_string This option causes ppmlabel to draw the specified text string. It advances the location for subsequent text by 1.75 times the current textsize, which allows drawing multiple lines of text in a reasonable manner without specifying the position of each line. Note that if you invoke ppmlabel via a shell command and your text string contains spaces, you'll have to quote it so the shell treats the whole string as a single token. E.g. $ ppmlabel -text "this is my text" baseimage.ppm >annotatedimage.ppm -x column This option sets the pixel column at which subsequent text will be left justified. Depending on the shape of the first character, the actual text may begin a few pixels to the right of this point. -y row This option sets the pixel row which will form the baseline of subsequent text. Characters with descenders, such as "y," will extend below this line. LIMITATIONS Text strings are restricted to 7 bit ASCII. The text font used by ppmdraw doesn't include definitions for 8 bit ISO 8859/1 characters. When drawing multiple lines of text with a non-transparent background, it should probably fill the space between the lines with the background color. This is tricky to get right when the text is rotated to a non-orthogonal angle. SEE ALSO ppmmake, pbmtext, pbmtextps, pamcomp, ppm AUTHOR Copyright (C) 1995 by John Walker (kelvin@fourmilab.ch) WWW home page: http://www.fourmilab.ch/ Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, without any conditions or restrictions. This software is provided ``as is'' without express or implied warranty. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS LIMITATIONS SEE ALSO AUTHOR øppmshadow Updated: 30 January 2004 Table Of Contents NAME ppmshadow - add simulated shadows to a PPM image SYNOPSIS ppmshadow [-b blur_size] [-k] [-t] [-x xoffset] [-y yoffset] [ppmfile] DESCRIPTION This program is part of Netpbm. ppmshadow adds a simulated shadow to an image, giving the appearance that the contents of the image float above the page, casting a diffuse shadow on the background. Shadows can either be black, as cast by opaque objects, or translucent, where the shadow takes on the color of the object which casts it. You can specify the extent of the shadow and its displacement from the image with command line options. OPTIONS -b blur_size Sets the distance of the light source from the image. Larger values move the light source closer, casting a more diffuse shadow, while smaller settings move the light further away, yielding a sharper shadow. blur_size defaults to 11 pixels. -k Keep the intermediate temporary image files. When debugging, these intermediate files provide many clues as to the source of an error. See below for a list of the contents of each file. -t Consider the non-background material in the image translucent -- it casts shadows of its own color rather than a black shadow, which is default. This often results in fuzzy, difficult-to-read images but in some circumstances may look better. -x xoffset Specifies the displacement of the light source to the left of the image. Larger settings of xoffset displace the shadow to the right, as would be cast by a light further to the left. If not specified, the horizontal offset is half of blur_size (above), to the left. -y yoffset Specifies the displacement of the light source above the top of the image. Larger settings displace the shadow downward, corresponding to moving the light further above the top of the image. If you don't specify -y, the vertical offset defaults to the same as the horizontal offset (above), upward. FILES Input is a PPM file named by the ppmfile command line argument; if you don't specify ppmfile, the input is Standard Input. The output is a PPM file, written to Standard Output. ppmshadow creates a number of temporary files as it executes. It creates a new directory for them, /tmp/ppmshadowpid, where pid is the process ID of the ppmshadow process. If the TMPDIR environment variable is set, ppmshadow creates the directory there instead of /tmp. In normal operation, ppmshadow deletes each temporary file as soon as it is done with it and leaves no debris around after it completes. To preserve the intermediate files for debugging, use the -k command line option. The temporary files are: infile.ppm A copy of the input. bgmask.ppm Positive binary mask convkernel.ppm Convolution kernel for blurring shadow blurred.ppm Blurred, colored shadow image blurred2.ppm Blurred shadow image before coloring shadow.ppm Clipped shadow image, offset as requested background.ppm Blank image with background of source image shadow.ppm Offset shadow fgmask.ppm Inverse mask file justfg.ppm Just the foreground. Rest is black. Original image times inverse mask. shadback.ppm Generated shadow times positive mask allbutfg.ppm Everything but the foreground (foreground area is black). LIMITATIONS The source image must contain sufficient space on the edges in the direction in which the shadow is cast to contain the shadow -- if it doesn't some of the internal steps may fail. You can usually expand the border of a too-tightly-cropped image with pnmmargin before processing it with ppmshadow. Black pixels and pixels with the same color as the image background don't cast a shadow. If this causes unintentional "holes" in the shadow, fill the offending areas with a color which differs from black or the background by RGB values of 1, which will be imperceptible to the viewer. Since the comparison is exact, the modified areas will now cast shadows. The background color of the source image (which is preserved in the output) is deemed to be the color of the pixel at the top left of the input image. If that pixel isn't part of the background, simply add a one-pixel border at the top of the image, generate the shadow image, then delete the border from it. If something goes wrong along the way, the error messages from the various Netpbm programs ppmshadow calls will, in general, provide little or no clue as to where ppmshadow went astray. In this case, Specify the -k option and examine the intermediate results in the temporary files (which this option causes to be preserved). If you manually run the commands that ppmshadow runs on these files, you can figure out where the problem is. In problem cases where you want to manually tweak the image generation process along the way, you can keep the intermediate files with the -k option, modify them appropriately with an image editor, then recombine them with the steps used by the code in ppmshadow. See the ppmshadow.doc file in the Netpbm source tree for additional details and examples of the intermediate files and debugging ppmshadow. Shadows are by default black, as cast by opaque material in the image occluding white light. Use the -t option to simulate translucent material, where the shadow takes on the color of the object that casts it. If the contrast between the image and background is insufficient, the -t option may yield unattractive results which resemble simple blurring of the original image. Because Netpbm used to have a maximum maxval of 255, which meant that the largest convolution kernel pnmconvol could use was 11 by 11, ppmshadow includes a horrid, CPU-time-burning kludge which, if a blur of greater than 11 is requested, performs an initial convolution with an 11×11 kernel, then calls pnmsmooth (which is itself a program that calls pnmconvol with a 3×3 kernel) as many times as the requested blur exceeds 11. It's ugly, but it gets the job done on those rare occasions where you need a blur greater than 11. If you wish to generate an image at high resolution, then scale it to publication size with pnmscale in order to eliminate jagged edges by resampling, it's best to generate the shadow in the original high resolution image, prior to scaling it down in size. If you scale first and then add the shadow, you'll get an unsightly jagged stripe between the edge of material and its shadow, due to resampled pixels intermediate between the image and background obscuring the shadow. EXIT STATUS ppmshadow returns status 0 if processing was completed without errors, and a nonzero Unix error code if an error prevented generation of output. Some errors may result in the script aborting, usually displaying error messages from various Netpbm components it uses, without returning a nonzero error code. When this happens, the output file will be empty, so be sure to test this if you need to know if the program succeeded. SEE ALSO pnm, pnmmargin, pnmconvol, pnmscale, pnmsmooth, ppm AUTHOR John Walker August 8, 1997 COPYRIGHT This software is in the public domain. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, without any conditions or restrictions. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS FILES LIMITATIONS EXIT STATUS SEE ALSO AUTHOR COPYRIGHT øppmbrighten Updated: 09 January 2003 Table Of Contents NAME ppmbrighten - change a PPM image's Saturation and Value SYNOPSIS ppmbrighten [-normalize] [-saturation [+|-saturation_percent]] [-value [+|-value_percent]] ppmfile All options can be abbreviated to their shortest unique prefix. DESCRIPTION This program is part of Netpbm. ppmbrighten increases or decreases the Saturation and Value (from the HSV color space) of each pixel of a PPM image. You specify the per centage change for each of those parameters. You can also remap the colors of the pixels so their Values cover the full range of possible Values. Hue-Saturation-Value, or HSV, is one way to represent a color, like the more well-known RGB. Hue, Saturation, and Value are numbers in the range from 0 to 1. We always capitalize them in this document when we mean the number from the HSV color space, especially since "value" as a conventional English word has a much more abstract meaning. Value is a measure of how much total light intensity is in the color, relative to some specified maximum (the PPM format is also defined in terms of a specified maximum intensity -- For the purposes of this program, they are the same). In particular, it is the intensity of the most intense primary color component of the color divided by the maximum intensity possible for a component. Zero Value means black. White has full Value. Hue is an indication of the secondary color with the same intensity that most closely approximates the color. A secondary color is made of a combination of at most two of the primary colors. Saturation is a measure of how close the color is to the color indicated by the Hue and Value. A lower number means more light of the third primary color must be added to get the exact color. Full Saturation means the color is a secondary color. Zero Saturation means the color is gray (or black or white). Decreasing the saturation of a color tends to make it washed out. If it is impossible to increase the Value of a pixel by the amount you specify (e.g. the Value is .5 and you specify +200%), ppmbrighten increases it to full Value instead. If it is impossible to increase the Saturation of a pixel by the amount you specify (e.g. it is already half saturated and you specify +200%), ppmbrighten increases it to full Saturation instead. For a simpler kind of brightening, you can use pamfunc -multiplier simply to increase the intensity of each pixel by a specified per centage, clipping each RGB component where the calculated intensity would exceed full intensity. Thus, the brightest colors in the image would change chromaticity in addition to not getting the specified intensity boost. For decreasing brightness, pamfunc should do the same thing as ppmbrighten. ppmflash does another kind of brightening. It changes the color of each pixel to bring it a specified per centage closer to white. This increases the value and saturation. EXAMPLES To double the Value of each pixel: ppmbrighten -v 100 To double the Saturation and halve the value of each pixel: ppmbrighten -s 100 -v -50 OPTIONS -value value_percent This option specifies the amount, as a per centage, by which you want to change the Value of each pixel. It may be negative. -saturation value_percent This option specifies the amount, as a per centage, by which you want to change the Saturation of each pixel. It may be negative. -normalize This option causes ppmbrighten to linearly remap the Values of the pixels to cover the range 0 to 1. The option name is wrong -- this operation is not normalization (it was named in error and the name has been kept for backward compatibility). ppmbrighten applies the brightening that you specify with the -value option after the remapping. Before Netpbm 10.14 (March 2003), your input must be from a seekable file (not a pipe) to use -normalize. If it isn't, the program fails with a bogus error message. SEE ALSO pgmnorm, ppmdim, pamfunc, ppmflash, pnmdepth, pnmgamma, ppmhist, ppm 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 documentation. This software is provided "as is" without express or implied warranty. Table Of Contents NAME SYNOPSIS DESCRIPTION EXAMPLES OPTIONS SEE ALSO AUTHOR øppmflash Updated: 26 January 2003 Table Of Contents NAME ppmflash - brighten a picture to approach white SYNOPSIS ppmflash flashfactor [ppmfile] DESCRIPTION This program is part of Netpbm. ppmflash reads a PPM image as input. It changes the color of each pixel to bring it a specified amount closer to white. It generates a PPM image of the result. flashfactor is a real number between 0 and 1, inclusive. ppmflash increases the intensity of each RGB component by the fraction flashfactor of the difference between the current value and full intensity. So if a pixel contains 60% full red, 10% full green, and no blue and you specify 0.5 (half), ppmflash increases the red to 80% (because it was 40% from full intensity, so it adds half of 40% to the original 60%), the green to 55%, and the blue to 50%. If flashfactor is zero, the output is identical to the input. If flashfactor is one, the output is all white. ppmbrighten does a more normal kind of brightening. pamfunc does a very simple brightening. Both ppmbrighten and pamfunc can reduce brightness as well. pnmgamma is another way people do a similar brightening, though it isn't really intended for that. SEE ALSO ppmbrighten pamfunc, pnmgamma, ppm, AUTHOR Copyright (C) 1993 by Frank Neumann Table Of Contents NAME SYNOPSIS DESCRIPTION SEE ALSO AUTHOR øppmdim Updated: June 2002 Table Of Contents NAME ppmdim - dim a PPM image SYNOPSIS ppmdim dimfactor [ppmfile] DESCRIPTION This program is part of Netpbm. This program is largely obsoleted by the more general pamfunc (use the -multiplier option). ppmdim remains for backward compatibility and also because its use of integer arithmetic may make it faster. ppmdim reads a PPM image input. Diminishes its brightness by the specified dimfactor. The dimfactor may be in the range from 0.0 (total blackness, deep night, nada, null, nothing) to 1.0 (original picture's brightness). SEE ALSO ppm, pamfunc, AUTHOR Copyright (C) 1993 by Frank Neumann Table Of Contents NAME SYNOPSIS DESCRIPTION SEE ALSO AUTHOR øPPMFADE Updated: April 1, 2000 Table Of Contents NAME ppmfade - generate a transition between two image files using special effects SYNOPSIS ppmfade [-f first.ppm] [-l last.ppm] [-mix|-spread|-shift| -relief|-oil|-edge|-bentley|-block] [-base name] DESCRIPTION This program is part of Netpbm. ppmfadegenerates a transition between either two input images or between one input image and black. You can use the 30 intermediate images generated to show a smooth transition between segments of a movie. The input and output images are in the PPM format. If you specify both input images, they should both be the same size. If you want to fade from black to an image, specify only the last image. If you want to fade from an image to black, specify only the first image. ppmfade names the resulting image files base.nnnn.ppm, where nnnn is a number varying between 0001 and 0030 and base is what you specify with via the -base option (default fade). Another way to convert by steps from one image to another is morphing. You can use xmorph to do that. OPTIONS -f first.ppm This is the image file (PPM format) to be used at the beginning of the transition. If you don't specify this, the fade will start from black. -l last.ppm This is the image file (PPM format) to be used at the ending of the transition. If you don't specify this, the fade will end with black. -mix The two images are superimposed with the brightness of the first image decreasing from full to none and the brightness of the final image increasing from none to full. The transition is quadratic in brightness with faster transition in the beginning and slower at the end. -spread The pixels in the first image will be moved (spread) further and further from their original location and then moved into the proper location in the final image. This is the default transition. -shift The pixels in the first image will be shifted further and further horizontally from their original location and then moved into the proper location in the final image. -relief The first image is faded to a Laplacian relief filtered version of the first image. This is then faded to a Laplacian relief filtered version of the second image and finally faded to the final image. -oil The first image is faded to an "oil transfer" version of the first image. This is then faded to an "oil transfer" version of the second image and finally faded to the final image. -edge The first image is faded to an edge detected version of the first image. This is then faded to an edge detected version of the second image and finally faded to the final image. -bentley The first image is faded to a "Bentley Effect" version of the first image. This is then faded to a "Bentley Effect" version of the second image and finally faded to the final image. -block The first image is defocused to small blocks. The small blocks are converted to match a defocused version of the last image. The block version of the last image is then focused to the final image. -base name This forms part of the output filenames, as described above. EXAMPLES ppmfade -f teapot.ppm -l pyr.ppm Fade from teapot.ppm to pyr.ppm generating fade.0001.ppm to fade.0030.ppm using the "spread" transition. ppmfade -l teapot.ppm Fade from black to teapot.ppm generating fade.0001.ppm to fade.0030.ppm. ppmfade -f teapot.ppm -base end Fade from teapot.ppm to black generating end.0001.ppm to end.0030.ppm. SEE ALSO tontsc manual, sgifade manual, smart_vfr manual, xmorph manual, ppm AUTHOR Bryan Henderson, Olympia WA; April 2000 Inspired by and intended as a replacement for pbmfade (not a Netpbm program) by Wesley C. Barris. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS EXAMPLES SEE ALSO AUTHOR øpbmreduce Updated: 02 August 1989 Table Of Contents NAME pbmreduce - read a PBM image and reduce it N times SYNOPSIS pbmreduce [-floyd|-fs|-threshold] [-value val] N [pbmfile] You can abbreviate any option to its shortest unique prefix. DESCRIPTION This program is part of Netpbm. pbmreduce reads a PBM image as input and reduces it by a factor of N, producing a PBM image as output. pbmreduce duplicates a lot of the functionality of pgmtopbm; you could do something like pnmscale | pgmtopbm, but pbmreduce is a lot faster. You can use pbmreduce 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 option. OPTIONS By default, pbmreduce does the halftoning after the reduction via boustrophedonic Floyd-Steinberg error diffusion; however, you can use the -threshold option to specify simple thresholding. This gives better results when reducing line drawings. The -value option alters the thresholding value for all quantizations. It should be a real number between 0 and 1. Above 0.5 means darker images; below 0.5 means lighter. SEE ALSO pnmenlarge, pnmscale, pgmtopbm, pbm AUTHOR Copyright (C) 1988 by Jef Poskanzer. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO AUTHOR øpnmnorm Updated: 7 October 1993 Table Of Contents NAME pnmnorm - normalize the contrast in a Netbpm image SYNOPSIS pnmnorm [-bpercent N | -bvalue N] [-wpercent N | -wvalue N] [-keephues] [-brightmax] [ppmfile] All options can be abbreviated to their shortest unique prefix. You may use two hyphens instead of one to designate an option. You may use either white space or an equals sign between an option name and its value. DESCRIPTION This program is part of Netpbm. pnmnorm reads a PNM image (PBM, PGM, or PPM). Normalizes the contrast by forcing the lightest pixels to white, the darkest pixels to black, and linearly rescaling the ones in between; and produces the same kind of file as output. This is pretty useless for a PBM image. The program first determines a mapping of old brightness to new brightness. For each possible brightness of a pixel, the program determines a corresponding brightness for the output image. Then for each pixel in the image, the program computes a color which has the desired output brightness and puts that in the output. With a color image, it is not always possible to compute such a color and retain any semblance of the original hue, so the brightest and dimmest pixels may only approximate the desired brightness. Note that for a PPM image, this is different from separately normalizing the individual color components. 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. You can get appropriate numbers for the flags from ppmhist. 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. If you specify both -bvalue and -bpercent, pnmnorm uses the one that produces the minimal change. The same goes for -wvalue and -wpercent. If you want to maximize the change instead of minimizing it, just cascade two runs of pnmnorm, specifying values for the first and percentages for the second. Before Netpbm 10.26 (December 2004), it was not valid to specify both -bvalue and -bpercent or -wvalue and -wpercent. The -keephues option says to keep each pixel the same hue as it is in the input; just adjust its intensity. By default, pnmnorm normalizes contrast in each component independently (except that the meaning of the -wpercent and -bpercent options are based on the overall intensities of the colors, not each component taken separately). So if you have a color which is intensely red but dimly green, pnmnorm would make the red more intense and the green less intense, so you end up with a different hue than you started with. If you specify -keephues, pnmnorm would likely leave this pixel alone, since its overall intensity is medium. -keephues can cause clipping, because a certain color may be below a target intensity while one of its components is saturated. Where that's the case, pnmnorm uses the maximum representable intensity for the saturated component and the pixel ends up with less overall intensity, and a different hue, than it is supposed to have. This option is meaningless on grayscale images. Before March 2002, there was no -keephues option. The -brightmax option says to use the intensity of the most intense RGB component of a pixel as the pixel's brightness. By default, pnmnorm uses the luminosity of the color as its brightness. This option is meaningless on grayscale images. Before March 2002, there was no -brightmax option. SEE ALSO ppmhist, pgmhist, pnmgamma, ppmbrighten, ppmdim, pnm Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO øpbmpscale Updated: 03 October 2003 Table Of Contents NAME pbmpscale - enlarge a PBM image with edge smoothing SYNOPSIS pbmpscale N [pbmfile] DESCRIPTION This program is part of Netpbm. pbmpscale reads a PBM image as input, and outputs a PBM image enlarged N times. pbmpscale does this enlargement by pixel replication, with some additional smoothing of corners and edges. SEE ALSO pnmenlarge, pnmscale, pbm 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 documentation. This software is provided "as is" without express or implied warranty. NOTES pbmpscale works best for enlargements of 2. Enlargements greater than 2 should be done by as many enlargements of 2 as possible, followed by an enlargement by the remaining factor. Table Of Contents NAME SYNOPSIS DESCRIPTION SEE ALSO AUTHOR NOTES øpamscale Updated: 18 February 2005 Table Of Contents NAME pamscale - scale a Netpbm image SYNOPSIS pamscale [ scale_factor | {-xyfit | -xyfill | -xysize} cols rows | -reduce reduction_factor | [-xsize=cols | -width=cols | -xscale=factor] [-ysize=rows | -height=rows | -yscale=factor] | -pixels n ] [ [-verbose] [ -nomix | -filter=functionName [-window=functionName] ] [-linear] } [pnmfile] Minimum unique abbreviation of option is acceptable. You may use double hypens instead of single hyphen to denote options. You may use white space in place of the equals sign to separate an option name from its value. DESCRIPTION This program is part of Netpbm. pamscale scales a Netpbm image by a specified factor, or scales individually horizontally and vertically by specified factors. You can both enlarge (scale factor > 1) and reduce (scale factor < 1). The Scale Factors When you specify an absolute size or scale factor for both dimensions, pamscale scales each dimension independently without consideration of the aspect ratio. If you specify one dimension as a pixel size and don't specify the other dimension, pamscale scales the unspecified dimension to preserve the aspect ratio. If you specify one dimension as a scale factor and don't specify the other dimension, pamscale leaves the unspecified dimension unchanged from the input. If you specify the scale_factor parameter instead of dimension options, that is the scale factor for both dimensions. It is equivalent to -xscale=scale_factor -yscale=scale_factor. Specifying the -reduce reduction_factor option is equivalent to specifying the scale_factor parameter, where scale_factor is the reciprocal of reduction_factor. -xyfit specifies a bounding box. pamscale scales the input image to the largest size that fits within the box, while preserving its aspect ratio. -xysize is a synonym for this. Before Netpbm 10.20 (January 2004), -xyfit did not exist, but -xysize did. -xyfill is similar, but pamscale scales the input image to the smallest size that completely fills the box, while preserving its aspect ratio. This option has existed since Netpbm 10.20 (January 2004). -pixels specifies a maximum total number of output pixels. pamscale scales the image down to that number of pixels. If the input image is already no more than that many pixels, pamscale just copies it as output; pamscale does not scale up with -pixels. 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. When the scale factor is not an integer (including all cases of scaling down), there are two ways to do the scaling. Which one pamscale does is controlled by its -nomix option. Usage Notes A useful application of pamscale is to blur an image. Scale it down (without -nomix ) to discard some information, then scale it back up using pamstretch. Or scale it back up with pamscale and create a "pixelized" image, which is sort of a computer-age version of blurring. Transparency pamscale understands transparency and properly mixes pixels considering the pixels' transparency. Proper mixing does not mean just mixing the transparency value and the color component values separately. In a PAM image, a pixel which is not opaque represents a color that contains light of the foreground color indicated explicitly in the PAM and light of a background color to be named later. But the numerical scale of a color component sample in a PAM is as if the pixel is opaque. So a pixel that is supposed to contain half-strength red light for the foreground plus some light from the background has a red color sample that says full red and a transparency sample that says 50% opaque. In order to mix pixels, you have to first convert the color sample values to numbers that represent amount of light directly (i.e. multiply by the opaqueness) and after mixing, convert back (divide by the opaqueness). Input And Output Image Types pamscale produces output of the same type (and tuple type if the type is PAM) as the input, except if the input is PBM. In that case, the output is PGM with maxval 255. The purpose of this is to allow meaningful pixel mixing. Note that there is no equivalent exception when the input is PAM. If the PAM input tuple type is BLACKANDWHITE, the PAM output tuple type is also BLACKANDWHITE, and you get no meaningful pixel mixing. If you want PBM output with PBM input, use pgmtopbm to convert pamscale's output to PBM. Also consider pbmreduce. pamscale's function is essentially undefined for PAM input images that are not of tuple type RGB, GRAYSCALE, BLACKANDWHITE, or the _ALPHA variations of those. (By standard Netpbm backward compatibility, this includes PBM, PGM, and PPM images). You might think it would have an obvious effect on other tuple types, but remember that the aforementioned tuple types have gamma-adjusted sample values, and pamscale uses that fact in its calculations. And it treats a transparency plane different from any other plane. pamscale does not simply reject unrecognized tuple types because there's a possibility that just by coincidence you can get useful function out of it with some other tuple type and the right combination of options (consider -linear in particular). Methods Of Scaling There are numerous ways to scale an image. pamscale implements a bunch of them; you select among them with invocation options. Pixel Mixing Pamscale's default method is pixel mixing. To understand this, imagine the source image as composed of square tiles. Each tile is a pixel and has uniform color. The tiles are all the same size. Now lay over that a transparent sheet of the same size, marked off in a square grid. Each cell in the grid stands for a pixel of the target image. For example, if you are scaling a 100x200 image up by 1.5, the source image is 100 x 200 tiles, and the transparent sheet is marked off in 150 x 300 cells. Each cell covers parts of multiple tiles. To make the target image, just color in each cell with the color which is the average of the colors the cell covers -- weighted by the amount of that color it covers. A cell in our example might cover 4/9 of a blue tile, 2/9 of a red tile, 2/9 of a green tile, and 1/9 of a white tile. So the target pixel would be somewhat unsaturated blue. When you are scaling up or down by an integer, the results are simple. When scaling up, pixels get duplicated. When scaling down, pixels get thrown away. In either case, the colors in the target image are a subset of those in the source image. When the scale factor is weirder than that, the target image can have colors that didn't exist in the original. For example, a red pixel next to a white pixel in the source might become a red pixel, a pink pixel, and a white pixel in the target. This method tends to replicate what the human eye does as it moves closer to or further away from an image. It also tends to replicate what the human eye sees, when far enough away to make the pixelization disappear, if an image is not made of pixels and simply stretches or shrinks. Discrete Sampling Discrete sampling is basically the same thing as pixel mixing except that, in the model described above, instead of averaging the colors of the tiles the cell covers, you pick the one color that covers the most area. The result you see is that when you enlarge an image, pixels get duplicated and when you reduce an image, some pixels get discarded. The advantage of this is that you end up with an image made from the same color palette as the original. Sometimes that's important. The disadvantage is that it distorts the picture. If you scale up by 1.5 horizontally, for example, the even numbered input pixels are doubled in the output and the odd numbered ones are copied singly. If you have a bunch of one pixel wide lines in the source, you may find that some of them stretch to 2 pixels, others remain 1 pixel when you enlarge. When you reduce, you may find that some of the lines disappear completely. You select discrete sampling with pamscale's -nomix option. Actually, -nomix doesn't do exactly what I described above. It does the scaling in two passes - first horizontal, then vertical. This can produce slightly different results. One case that people often find it burdensome to have pamscale make up colors that weren't there originally is when they are working with an image format such as GIF that has a limited number of possible colors per image. If you take a GIF with 256 colors, convert it to PPM, scale by .625, and convert back to GIF, you will probably find that the reduced image has way more than 256 colors, and therefore cannot be converted to GIF. One way to solve this problem is to do the reduction with discrete sampling instead of pixel mixing. Probably a better way is to do the pixel mixing, but then color quantize the result with pnmquant before converting to GIF. When the scale factor is an integer (which means you're scaling up), discrete sampling and pixel mixing are identical -- output pixels are always just N copies of the input pixels. In this case, though, consider using pamstretch instead of pamscale to get the added pixels interpolated instead of just copied and thereby get a smoother enlargement. pamscale's discrete sampling is faster than pixel mixing, but pnmenlarge is faster still. pnmenlarge works only on integer enlargements. discrete sampling (-nomix) was new in Netpbm 9.24 (January 2002). Resampling Resampling assumes that the source image is a discrete sampling of some original continuous image. That is, it assumes there is some non-pixelized original image and each pixel of the source image is simply the color of that image at a particular point. Those points, naturally, are the intersections of a square grid. The idea of resampling is just to compute that original image, then sample it at a different frequency (a grid of a different scale). The problem, of course, is that sampling necessarily throws away the information you need to rebuild the original image. So we have to make a bunch of assumptions about the makeup of the original image. You tell pamscale to use the resampling method by specifying the -filter option. The value of this option is the name of a function, from the set listed below. To explain resampling, we are going to talk about a simple one dimensional scaling -- scaling a single row of grayscale pixels horizontally. If you can understand that, you can easily understand how to do a whole image: Scale each of the rows of the image, then scale each of the resulting columns. And scale each of the color component planes separately. As a first step in resampling, pamscale converts the source image, which is a set of discrete pixel values, into a continuous step function. A step function is a function whose graph is a staircase-y thing. Now, we convolve the step function with the filter function that you identified with -filter. If you don't know what the mathematical concept of convolution (convolving) is, you are officially lost. You cannot understand this explanation. The result of this convolution is the imaginary original continuous image we've been talking about. Finally, we make target pixels by picking values from that function. For some filter functions, it is easy to see what's going on. The impulse filter assumes that the original continuous image is in fact a step function -- the very one we already computed. The box (rectangle) filter assumes the original image is a piecewise linear function. Its graph just looks like straight lines connecting the pixel values. The more complex filter functions require Fourier analysis to understand: The idea is that the only difference between our step function and the original continuous function (remember that we constructed the step function from the source image, which is itself a sampling of the original continuous function) is that the step function has a bunch of high frequency Fourier components added. If we could chop out all the higher frequency components of the step function, we'd have the original function back, minus whatever high frequency components the original function has. While losing those original high frequency components is not nice, the idea is that the high frequency components are the ones the user of our target image (a human eye, for example) is least likely to miss. To chop out all the components above a certain frequency, we just multiply the Fourier transform of the step function by a rectangle function. We could find the Fourier transform of the step function, multiply it by a rectangle function, and then Fourier transform the result back, but there's an easier way. Mathematicians tell us that multiplying in the frequency domain is equivalent to convolving in the time domain. That means multiplying the Fourier transform of F by a rectangle function R is the same as convolving F with the Fourier transform of R. It's a lot better to take the Fourier transform of R, and build it into pamscale than to have pamscale take the Fourier transform of the input image dynamically. That leaves only one question: What is the Fourier transform of a rectangle function? Answer: sinc. Recall from math that sinc is defined as sinc(x) = sin(PI*x)/PI*x. Hence, when you specify -filter=sinc, you are effectively passing the step function of the source image through a low pass frequency filter and recovering a good approximation of the original continuous image. Unfortunately, pamscale doesn't do the convolution precisely. Instead of evaluating the filter function at every point, it samples it -- assumes that it doesn't change any more often than the step function does. pamscale could actually do the true integration fairly easily. Since the filter functions are built in to the program, the integrals of them could be too. Maybe someday it will. There is one more complication with the Fourier analysis. sinc has nonzero values on out to infinity and minus infinity. That makes it hard to compute a convolution with it. So instead, there are filter functions that approximate sinc but are nonzero only within a manageable range. To get those, you multiply the sinc function by a window function, which you select with the -window option. The same holds for other filter functions that go on forever like sinc. By default, for a filter that needs a window function, the window function is the Blackman function. Resampling is not generally a good method for reducing an image, especially for reducing by more than a factor of 2. Reconstructing missing colors between pixels doesn't help you much when you're trying to take what was 5 pixels and represent it as one. Simple averaging (pixel mixing) works best for that. pamscale assumes the underlying continuous function is a function of brightness (as opposed to light intensity), and therefore does all this math using the gamma-adjusted numbers found in a PNM or PAM image. The -linear option is not available with resampling (it causes pamscale to fail), because it wouldn't be useful enough to justify the implementation effort. Resampling (-filter) was new in Netpbm 10.20 (January 2004). The filter functions Here is a list of the function names you can specify for the -filter option. For most of them, you're on your own to figure out just what the function is and what kind of scaling it does. These are common functions from mathematics. point The graph of this is a single point at X=0, Y=1. box The graph of this is a rectangle sitting on the X axis and centered on the Y axis with height 1 and base 1. triangle The graph of this is an isosceles triangle sitting on the X axis and centered on the Y axis with height 1 and base 2. quadratic cubic catrom mitchell gauss sinc bessel hanning hamming blackman kaiser normal hermite lanczos Linear vs Gamma-adjusted The pixel mixing scaling method described above involves intensities of pixels (more precisely, it involves individual intensities of primary color components of pixels). But the PNM and PNM-equivalent PAM image formats represent intensities with gamma-adjusted numbers that are not linearly proportional to intensity. So pamscale, by default, performs a calculation on each sample read from its input and each sample written to its output to convert between these gamma-adjusted numbers and internal intensity-proportional numbers. Sometimes you are not working with true PNM or PAM images, but rather a variation in which the sample values are in fact directly proportional to intensity. If so, use the -linear option to tell pamscale this. pamscale then will skip the conversions. The conversion takes time. In one experiment, it increased the time required to reduce an image by a factor of 10. And the difference between intensity-proportional values and gamma-adjusted values may be small enough that you would barely see a difference in the result if you just pretended that the gamma-adjusted values were in fact intensity-proportional. So just to save time, at the expense of some image quality, you can specify -linear even when you have true PPM input and expect true PPM output. For the first 13 years of Netpbm's life, until Netpbm 10.20 (January 2004), pamscale's predecessor pnmscale always treated the PPM samples as intensity-proportional even though they were not, and drew few complaints. So using -linear as a lie is a reasonable thing to do if speed is important to you. But if speed is important, you also should consider the -nomix option and pnmscalefixed. Another technique to consider is to convert your PNM image to the linear variation with pnmgamma, run pamscale on it and other transformations that like linear PNM, and then convert it back to true PNM with pnmgamma -ungamma. pnmgamma is often faster than pamscale in doing the conversion. With -nomix, -linear has no effect. That's because pamscale does not concern itself with the meaning of the sample values in this method; pamscale just copies numbers from its input to its output. Precision pamscale uses floating point arithmetic internally. There is a speed cost associated with this. For some images, you can get the acceptable results (in fact, sometimes identical results) faster with pnmscalefixed, which uses fixed point arithmetic. pnmscalefixed may, however, distort your image a little. See the pnmscalefixed user manual for a complete discussion of the difference. SEE ALSO pnmscalefixed, pamstretch, pbmreduce, pbmpscale, pnmenlarge, pnmsmooth, pamcut, pnmgamma, pnmscale, pnm, pam HISTORY pamscale was new in Netpbm 10.20 (January 2004). It was adapted from, and obsoleted, pnmscale. pamscale's primary difference from pnmscale is that it handles the PAM format and uses the "pam" facilities of the Netpbm programming library. But it also added the resampling class of scaling method. Furthermore, it properly does its pixel mixing arithmetic (by default) using intensity-proportional values instead of the gamma-adjusted values the pnmscale uses. To get the old pnmscale arithmetic, you can specify the -linear option. The intensity proportional stuff came out suggestions by Adam M Costello in January 2004. The resampling algorithms are mostly taken from code contributed by Michael Reinelt in December 2003. The version of pnmscale from which pamscale was derived, itself evolved out of the original Pbmplus version of pnmscale by Jef Poskanzer (1989, 1991). But none of that original code remains. Table Of Contents NAME SYNOPSIS DESCRIPTION The Scale Factors Usage Notes Input And Output Image Types Methods Of Scaling Pixel Mixing Discreate Sampling Resampling Linear vs Gamma-adjusted Precision SEE ALSO HISTORY øpnmscale Updated: 25 January 2004 Table Of Contents NAME pnmscale - scale a PNM image SYNOPSIS pnmscale [ scale_factor | -xysize cols rows | -reduce reduction_factor | [-xsize=cols | -width=cols | -xscale=factor] [-ysize=rows | -height=rows | -yscale=factor] | -pixels n ] [-verbose] [-nomix] [pnmfile] DESCRIPTION This program is part of Netpbm. pnmscale was obsoleted by pamscale, introduced with Netpbm 10.20 (January 2004). pamscale is backward compatible with pnmscale, plus adds many additional functions, including the ability to process PAM images, and tends to produce better results. pnmscale remains in the current Netpbm package because it probably has fewer bugs for now than pamscale, and may have superior performance characteristics in some cases. Some day, pnmscale will probably become an alias for pamscale. You can use the pamscale documentation for pnmscale, considering the following differences: pnmscale options are a subset of pamscale's, as documented above. pnmscale always assumes the input is linear, as pamscale does when you specify its -linear option. pnmscale cannot process PAM images. øpnmscalefixed Updated: 18 November 2000 Table Of Contents NAME pnmscale - scale a PNM file quickly DESCRIPTION This program is part of Netpbm. pnmscalefixed is the same thing as pnmscale except that it uses fixed point arithmetic internally instead of floating point, which makes it run faster. In turn, it is less accurate and may distort the image. Use the pnmscale user manual with pnmscalefixed. This document only describes the difference. pnmscalefixed uses fixed point 12 bit arithmetic. By contrast, pnmscale uses floating point arithmetic which on most machines is probably 24 bit precision. This makes pnmscalefixed run faster (30% faster in one experiment), but the imprecision can cause distortions at the right and bottom edges. The distortion takes the following form: One pixel from the edge of the input is rendered larger in the output than the scaling factor requires. Consequently, the rest of the image is smaller than the scaling factor requires, because the overall dimensions of the image are always as requested. This distortion will usually be very hard to see. pnmscalefixed with the -verbose option tells you how much distortion there is. The amount of distortion depends on the size of the input image and how close the scaling factor is to an integral 1/4096th. If the scaling factor is an exact multiple of 1/4096, there is no distortion. So, for example doubling or halving an image causes no distortion. But reducing it or enlarging it by a third would cause some distortion. To consider an extreme case, scaling a 100,000 row image down to 50,022 rows would create an output image with all of the input squeezed into the top 50,000 rows, and the last row of the input copied into the bottom 22 rows of output. pnmscalefixed could probably be modified to use 16 bit or better arithmetic without losing anything. The modification would consist of a single constant in the source code. Until there is a demonstrated need for that, though, the Netpbm maintainer wants to keep the safety cushion afforded by the original 12 bit precision. pnmscalefixed does not have pnmscale's -nomix option. Table Of Contents NAME DESCRIPTION øpgmedge Updated: September 2004 NAME pnmenlarge - replaced by pamenlarge DESCRIPTION This program is part of Netpbm. pnmenlarge was replaced in Netpbm 10.25 (October 2004) by pamenlarge. pamenlarge is backward compatible with pnmenlarge, but works on PAM images too. øpamperspective Updated: 2 September 2004 Table Of Contents NAME pamperspective - a reverse scanline renderer for Netpbm images SYNOPSIS pamperspective [--bottom_margin=num] [--detail=num] [--frame_include=bool] [--height=num] [--include=[x1,y1;x2,y2; ...]] [--input_system=spec] [--input_unit=spec] [--interpolation=spec] [--left_margin=num] [--margin=num] [--output_system=spec] [--proportion=spec] [--ratio=num] [--right_margin=num] [--top_margin=num] [--width=num] { { upper_left_x upper_left_y upper_right_x upper_right_y lower_left_x lower_left_y lower_right_x lower_right_y } | { {--upper_left_x|--ulx}=upper_left_x {--upper_left_y|--uly}=upper_left_y {--upper_right_x|--urx}=upper_right_x {--upper_right_y|--ury}=upper_right_y {--lower_left_x|--llx}=lower_left_x {--lower_left_y|--lly}=lower_left_y {--lower_right_x|--lrx}=lower_right_x {--lower_right_y|--lry}=lower_right_y } } [infile] Minimum unique abbreviation of option is acceptable. (But note that shortest unique prefixes might be longer in future versions of the program.) You may use single hypens instead of double hyphen to denote options. You may use white space in place of the equals sign to separate an option name from its value. All options starting with hyphens may be given in any order. DESCRIPTION This program is part of Netpbm. pamperspective reads a Netpbm image as input and produces a Netpbm image of the same format as output. The values upper_left_x ... lower_right_y, that are required on the command line, specify a quadrilateral in the input image. pamperspective interprets the input image as a perspective projection of a three dimensional scene, for example a photograph. pamperspective assumes the specified quadrilateral represents a parallelogram in that scene. The output image consists of this parallelogram, sheared to a rectangle. In this way pamperspective undoes the effect of a raytracer or scanline renderer. The input is from infile, or from Standard Input, if infile is not specified. The output is to Standard Output. OPTIONS For options of the form --name=num, You can specify the value num in any of the traditional ways. Additionally, you can specify it as num1/num2, where num1 and num2 are specified traditionally. This is useful for specifying a width/height ratio of 4/3, without having to write infinitely many digits. Where num is supposed to be a natural number, pamperspective does not allow this format. Quadrilateral specification options --upper_left_x=num --ulx=num This specifies the horizontal coordinate of the upper left vertex of the quadrilateral. The meaning of 'upper left' is relative to the output image. The interpretation of num depends on the values for --input_system and --input_unit. --upper_left_y=num --uly=num This specifies the vertical coordinate of the upper left vertex of the quadrilateral. The meaning of 'upper left' is relative to the output image. The interpretation of num depends on the values for --input_system and --input_unit. --upper_right_x=num --urx=num This specifies the horizontal coordinate of the upper right vertex of the quadrilateral. The meaning of 'upper right' is relative to the output image. The interpretation of num depends on the values for --input_system and --input_unit. --upper_right_y=num --ury=num This specifies the vertical coordinate of the upper right vertex of the quadrilateral. The meaning of 'upper right' is relative to the output image. The interpretation of num depends on the values for --input_system and --input_unit. --lower_left_x=num --llx=num This specifies the horizontal coordinate of the lower left vertex of the quadrilateral. The meaning of 'lower left' is relative to the output image. The interpretation of num depends on the values for --input_system and --input_unit. --lower_left_y=num --lly=num This specifies the vertical coordinate of the lower left vertex of the quadrilateral. The meaning of 'lower left' is relative to the output image. The interpretation of num depends on the values for --input_system and --input_unit. --lower_right_x=num --lrx=num This specifies the horizontal coordinate of the lower right vertex of the quadrilateral. The meaning of 'lower right' is relative to the output image. The interpretation of num depends on the values for --input_system and --input_unit. --lower_right_y=num --lry=num This specifies the vertical coordinate of the lower right vertex of the quadrilateral. The meaning of 'lower right' is relative to the output image. The interpretation of num depends on the values for --input_system and --input_unit. --input_system=system --input_unit=unit The input image consists of pixels, which are, from the point of view of a scanline renderer, solid squares. These options specify how the coordinates are interpreted: system=lattice, unit=image (0,0) refers to the upper left corner of the upper left pixel and (1,1) refers to the lower right corner of the lower right pixel. system=lattice, unit=pixel (0,0) refers to the upper left corner of the upper left pixel and (width,height) refers to the lower right corner of the lower right pixel. Here width and height are the width and height of the input image. system=pixel, unit=image (0,0) refers to the centre of the upper left pixel and (1,1) refers to the centre of the lower right pixel. system=pixel, unit=pixel (0,0) refers to the centre of the upper left pixel and (width-1,height-1) refers to the centre of the lower right pixel. Here width and height are the width and height of the input image. The defaults are --input_system=lattice and --input_unit=pixel. Point-and-click front ends should use --input_system=pixel. Frame options By default pamperspective outputs exactly the above parallelogram, sheared to a rectangle. With the following options, it is possible to make pamperspective output a larger or smaller portion, which we call the "visible part." We refer to the default rectangle as the "frame." The visible part is always a rectangle the axes of which are parallel to those of the frame. The frame options are additive. All the parts of the image specified by either margin options, --include_frame, or --include (or their defaults) are in the visible part. The visible part is the smallest possible rectangle that contains the parts specified those three ways. The visible part must have nonzero size. That means if you specify --frame-include=no (overriding the default), you'll need to specify other frame options in order to have something in the visible part. [--margin=num] This specifies an area surrounding the frame that is to be included in the visible part. The units of num are the width of the frame for the horizontal extensions and the height of the frame for vertical extensions. For example, --margin=1 makes the visible part 9 times as large, because it makes the visible part extend one frame's worth to the left of the frame, one frame's worth to the right, one frame's worth above the frame, and one frame's worth below the frame, for a total of 3 frames' worth in both dimensions. A negative value has an effect only if you specify --frame_include=no. The default is no margin. The individual margin options below override this common margin setting. [--top_margin=num] [--left_margin=num] [--right_margin=num] [--bottom_margin=num] These are like --margin, but they specify only one of the 4 sides. The default value for each is the value (or default) of --margin. [--frame_include=bool] Valid values for bool are: yes true on The frame itself is in the visible part. no false off The frame itself is not necessarily in the visible part (but it could be if other options cause it to be). The default value is yes --include=[x1,y1;x2,y2; ...] The visible part is made large enough such that every point (x1,y1), (x2,y2), of the input image is visible. The meaning of x and y is determined by --input_system and --input_unit. You can specify any number of semicolon-delimited points, including zero. If you're supplying these options via a Unix command shell, be sure to use proper quoting, because semicolon (;) is usually a shell control character. The frame options were new in Netpbm 10.25 (October 2004). Output size options --width=width --height=height These specify the size of the output image in horizontal and vertical direction. The values are numbers of pixels, so only natural numbers are valid. These values override the default means to determine the output size. --detail=num If you do not specify --width, pamperspective determines the width of the output image such that moving num output pixels horizontally does not change the corresponding pixel coordinates of the input image by more than 1. pamperspective determines the height of the output image analogously. The default value is 1. --proportion=prop --ratio=ratio Valid values for prop are: free In this case --ratio does not have any effect. fixed After the width and height are determined according to --detail, one of both will be increased, in order to obtain width/height=ratio. The defaults are --proportion=free and --ratio=1. Output options --output_system=spec The output image consists of pixels, which are, from the point of view of a scanline renderer, solid squares. This option specifies how the four vertices of the quadrilateral correspond to the pixels of the output image. Valid values for spec are: lattice The upper left vertex corresponds to the upper left corner of the upper left pixel and The lower right vertex corresponds to the lower right corner of the lower right pixel. pixel The upper left vertex corresponds to the centre of the upper left pixel and The lower right vertex corresponds to the centre of the lower right pixel. The default value is lattice. Point-and-click front ends should use pixel. --interpolation=spec Usually (centres of) output pixels do not exactly correspond to (centres of) input pixels. This option determines how the program will choose the new pixels. Valid values for spec are: nearest The output pixel will be identical to the nearest input pixel. linear The output pixel will be a bilinear interpolation of the four surrounding input pixels. The default value is nearest. HINTS It might be tempting always to use the options --include 0,0;0,1;1,0;1,1 (assuming --input_system=lattice and --input_unit=image), so that no part of the input image is missing in the output. There are problems with that: If the threedimensional plane defined by the quadrilateral has a visible horizon in the input image, then the above asks pamperspective to include points that cannot ever be part of the output. If the horizon is not visible, but close to the border of the input image, this may result in very large output files. Consider a picture of a road. If you ask a point close to the horizon to be included, then this point is far away from the viewer. The output will cover many kilometers of road, while --detail perhaps makes a pixel equal to a square centimeter. When working with large files pamperspective's memory usage might be an issue. In order to keep it small, you should minimize each of the following: The vertical range that the top output line consumes in the input image; The vertical range that the bottom output line consumes in the input image; The vertical range from the topmost (with respect to the input image) quadrilateral point to the top (with respect to the output image) output line. For this purpose you can use pamflip before and/or after pamperspective. Example: Instead of pamperspective 10 0 100 50 0 20 95 100 infile > outfile you can use pamflip -rotate90 infile | pamperspective 50 0 100 5 0 90 20 100 | pamflip -rotate270 > outfile SEE ALSO netpbm, pam, pnm, pamcut, pamflip, pnmrotate, pamscale, pnmshear, pnmstitch HISTORY Mark Weyer wrote pamperspective in March 2004. It was new in Netpbm 10.22 (April 2004). AUTHOR This documentation was written by Mark Weyer. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 or any later version published by the Free Software Foundation. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS HINTS SEE ALSO HISTORY AUTHOR øNetpbm Program Directory øppmdither Updated: 14 July 1991 Table Of Contents NAME ppmdither - ordered dither for color images SYNOPSIS ppmdither [-dim power] [-red shades] [-green shades] [-blue shades] [ppmfile] DESCRIPTION This program is part of Netpbm. ppmdither reads a PPM image 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. OPTIONS -dim power The size of the dithering matrix. The dithering matrix is a square whose dimension is a power of 2. power is that power of 2. The default is 4, for a 16 by 16 matrix. -red shades The number of red shades to be used, including black; minimum of 2. -green shades The number of green shades to be used, including black; minimum of 2. -blue shades The number of blue shades to be used, including black; minimum of 2. SEE ALSO pnmdepth, pnmquant, ppm AUTHOR Copyright (C) 1991 by Christos Zoulas. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO AUTHOR øpamditherbw Updated: 20 June 2004 Table Of Contents NAME pamditherbw - dither grayscale image to black and white SYNOPSIS pamditherbw [-floyd | -fs | -threshold | -hilbert | -dither8 | -d8 | -cluster3 | -c3 | -cluster4 | -c4 | -cluster8 | -c8] [-value val] [-clump size] [pamfile] DESCRIPTION This program is part of Netpbm. pamditherbw dithers a grayscale image. Dithering means turning each shade of gray into a pattern of black and white pixels that, from a distance, look the same as the gray. The input should be a PGM image or a PAM image of tuple type GRAYSCALE. However, pamditherbw doesn't check, so if you feed it e.g. a PPM image, it will produce arbitrary results (actually, it just takes the first channel of whatever you give it and treats it as if it represented gray levels). The output is a PAM with tuple type BLACKANDWHITE. You can turn this into a PBM (if you need to use it with an older program doesn't understand PAM) with pamtopnm. To do the opposite of dithering, you can usually just scale the image down and then back up again with pamscale, possibly smoothing or blurring the result with pnmsmooth or pnmconvol. Or use the special case program pbmtopgm. To dither a color image (to reduce the number of pixel colors), use ppmdither. 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). A space filling curve halftoning method using the Hilbert curve is also available (-hilbert). 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 option 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. The Hilbert curve method is useful for processing images before display on devices that do not render individual pixels distinctly (like laser printers). This dithering method can give better results than the dithering usually done by the laser printers themselves. The -clump option alters the number of pixels in a clump. This is usually an integer between 2 and 100 (default 5). Smaller clump sizes smear the image less and are less grainy, but seem to loose some grey scale linearity. Typically a PGM image will have to be scaled to fit on a laser printer page (2400 x 3000 pixels for an A4 300 dpi page), and then dithered to a PBM image before being converted to a postscript file. A printing pipeline might look something like: pamscale -xysize 2400 3000 image.pgm | pamditherbw -hilbert | \ pamtopnm | pnmtops -scale 0.25 > image.ps All options can be abbreviated to their shortest unique prefix. REFERENCES The only reference you need for this stuff is "Digital Halftoning" by Robert Ulichney, MIT Press, ISBN 0-262-21009-6. The Hilbert curve space filling method is taken from "Digital Halftoning with Space Filling Curves" by Luiz Velho, Computer Graphics Volume 25, Number 4, proceedings of SIGRAPH '91, page 81. ISBN 0-89791-436-8 SEE ALSO pamtopnm, pgmtopgm, pbmtopgm, pbmreduce, pnmconvol, pamscale, pam, pnm, HISTORY pamditherbw was new in Netpbm 10.23 (July 2004), but is essentially the same program as pgmtopbm that has existed practically since the beginning. pamditherbw differs from its predecessor in that it properly deals with gamma adjustment and that it accepts PAM input in addition to PGM and PBM and produces PAM output. pamditherbw obsoletes pgmtopbm. AUTHOR Copyright (C) 1989 by Jef Poskanzer. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS REFERENCES SEE ALSO AUTHOR øpnmcolormap Updated: 12 December 2001 Table Of Contents NAME pnmcolormap - create quantization color map for a Netpbm image SYNOPSIS pnmcolormap [-center|-meancolor|-meanpixel] [-spreadbrightness|-spreadluminosity] [-sort] [-square] ncolors|all [pnmfile] All options can be abbreviated to their shortest unique prefix. You may use two hyphens instead of one to designate an option. You may use either white space or an equals sign between an option name and its value. DESCRIPTION This program is part of Netpbm. pnmcolormap reads a PNM image as input, chooses ncolors colors to best represent the image, maps the existing colors to the new ones, and writes a PNM color map defining them as output. You can use this map as input to pnmremap on the same input image to quantize the colors in that image, I.e. produce a similar image with fewer colors. pnmquant does both the pnmcolormap and pnmremap steps for you. A PNM colormap is a PNM image of any dimensions that contains at least one pixel of each color in the set of colors it represents. The quantization method is Heckbert's "median cut". See QUANTIZATION METHOD. If the input image is a PPM, the output image is a PPM. If the input image is a PBM or PGM, the output colormap is a PGM. Note that a colormap of a PBM image is not very interesting. The colormap generally has the same maxval as the input image, but pnmcolormap may reduce it if there are too many colors in the input, as part of its quantization algorithm. If you want to create a colormap without basing it on the colors in an input image, see ppmcolors. PARAMETERS The single parameter, which is required, is the number of colors you want in the output colormap. pnmcolormap may produce a color map with slightly fewer colors than that. You may specify all to get a colormap of every color in the input image (no quantization). OPTIONS -sort This option causes the output colormap to be sorted by the red component intensity, then the green, then the blue in ascending order. This is an insertion sort, so it is not very fast on large colormaps. Sorting is useful because it allows you to compare two sets of colors. -square By default, pnmcolormap produces as the color map a PPM image with one row and one column for each color in the colormap. This option causes pnmcolormap instead to produce a PPM image that is within one row or column of being square, with multiple pixels of the same color as necessary to create a number of pixels which is a perfect square. -verbose This option causes pnmcolormap to display messages to Standard Error about the quantization. -center -meancolor -meanpixel -spreadbrightness -spreadluminosity These options control the quantization algorithm. See QUANTIZATION METHOD. QUANTIZATION METHOD A quantization method is a way to choose which colors, being fewer in number than in the input, you want in the output. pnmcolormap uses Heckbert's "median cut" quantization method. This method involves separating all the colors into "boxes," each holding colors that represent about the same number of pixels. You start with one box and split boxes in two until the number of boxes is the same as the number of colors you want in the output, and choose one color to represent each box. When you split a box, you do it so that all the colors in one sub-box are "greater" than all the colors in the other. "Greater," for a particular box, means it is brighter in the color component (red, green, blue) which has the largest spread in that box. pnmcolormap gives you two ways to define "largest spread.": 1) largest spread of brightness; 2) largest spread of contribution to the luminosity of the color. E.g. red is weighted much more than blue. Select among these with the -spreadbrightness and -spreadluminosity options. The default is -spreadbrightness. pnmcolormap provides three ways of choosing a color to represent a box: 1) the center color - the color halfway between the greatest and least colors in the box, using the above definition of "greater"; 2) the mean of the colors (each component averaged separately by brightness) in the box; 3) the mean weighted by the number of pixels of a color in the image. Note that in all three methods, there may be colors in the output which do not appear in the input at all. Select among these with the -center, -meancolor, and -meanpixel options. The default is -center. REFERENCES "Color Image Quantization for Frame Buffer Display" by Paul Heckbert, SIGGRAPH '82 Proceedings, page 297. SEE ALSO pnmremap, pnmquant, ppmquantall, pnmdepth, ppmdither, ppmquant, ppm HISTORY Before Netpbm 10.15 (April 2003), pnmcolormap used a lot more memory for large images because it kept the entire input image in memory. Now, it processes it a row at a time, but because it sometimes must make multiple passes through the image, it first copies the input into a temporary seekable file if it is not already in a seekable file. pnmcolormap first appeared in Netpbm 9.23 (January 2002). Before that, its function was available only as part of the function of pnmquant (which was derived from the much older ppmquant). Color quantization really has two main subfunctions, so Netpbm 9.23 split it out into two separate programs: pnmcolormap and pnmremap and then Netpbm 9.24 replaced pnmquant with a program that simply calls pnmcolormap and pnmremap. AUTHOR Copyright (C) 1989, 1991 by Jef Poskanzer. Table Of Contents NAME SYNOPSIS DESCRIPTION PARAMETERS OPTIONS QUANTIZATION METHOD REFERENCES SEE ALSO HISTORY AUTHOR øpnmremap Updated: 01 January 2002 Table Of Contents NAME pnmremap - replace colors in a PNM image with colors from another set SYNOPSIS pnmremap [-floyd|-fs|-nfloyd|-nofs] [-firstisdefault] [-verbose] [-mapfile=palettefile] [-missingcolor=color] [pnmfile] All options can be abbreviated to their shortest unique prefix. You may use two hyphens instead of one to designate an option. You may use either white space or an equals sign between an option name and its value. DESCRIPTION This program is part of Netpbm. pnmremap replaces the colors in an input image with those from a palette you specify. Where colors in the input are present in the palette, they just stay the same in the output. But where the input contains a color that is not in the palette, pnmremap gives you three choices: 1) choose the closest color from the palette; 2) choose the first color from the palette; 3) use a color specified by a command option. You can also dither, which means rather than mapping pixel by pixel, pnmremap uses colors from the palette to try to make multi-pixel regions of the output have the same average color as the input. Two reasons to do this are: 1) you want to reduce the number of colors in the input image; and 2) you need to feed the image to something that can handle only certain colors. To reduce colors, you can generate the palette with pnmcolormap. By default, pnmremap maps an input color that is not in the palette to the closest color that is in the palette. Closest means with the smallest cartesian distance in the red, green, blue brightness space (smallest sum of the squares of the differences in red, gree, and blue ITU Rec 709 gamma-adjusted intensities). You can instead specify a single default color for pnmremap to use for any color in the input image that is not in the palette. Use the -missing option for this. You can also specify that the first color in the palette image is the default. Use the -firstisdefault option for this. The palette is simply a PNM image. The colors of the pixels in the image are the colors in the palette. Where the pixels appear in the image, and the dimensions of the image, are irrelevant. Multiple pixels of the same color are fine. However, a palette image is typically a single row with one pixel per color. If you specify -missing, the color you so specify is in the palette in addition to whatever is in the palette image. For historical reasons, Netpbm sometimes calls the palette a "colormap." But it doesn't really map anything. pnmremap creates its own map, based on the palette, to map colors from the input image to output colors. Palette/Image Type Mismatch In the simple case, the palette image is of the same depth (number of planes, i.e. number of components in each tuple (pixel)) as the input image and pnmremap just does a straightforward search of the palette for each input tuple (pixel). In fact, pnmremap doesn't even care if the image is a visual image. But what about when the depths differ? In that case, pnmremap converts the input image (in its own memory) to match the palette and then proceeds as above. There are only two such cases in which pnmremap knows how to do the conversion when one of them is tuple type RGB, depth 3, and the other is tuple type GRAYSCALE or BLACKANDWHITE, depth 1; and vice versa. In any other case, pnmremap fails. Note that as long as your input and palette images are PNM, they'll always fall into one of the cases pnmremap can handle. There's an issue only if you're using some exotic PAM image. Before Netpbm 10.27 (March 2005), pnmremap could not handle the case of a palette of greater depth than the input image. In any case, the output image has the same tuple type and depth as the palette image. Examples pnmcolormap testimg.ppm 256 >palette.ppm pnmremap -map=palette.ppm testimg.ppm >reduced_testimg.ppm To limit colors to a certain set, a typical example is to create an image for posting on the World Wide Web, where different browsers know different colors. But all browsers are supposed to know the 216 "web safe" colors which are essentially all the colors you can represent in a PPM image with a maxval of 5. So you can do this: pamseq 3 5 >websafe.pam pnmremap -map=websafe.pam testimg.ppm >websafe_testimg.ppm Another useful palette is one for the 8 color IBM TTL color set, which you can create with pamseq 3 1 >ibmttl.pam If you want to quantize one image to use the colors in another one, just use the second one as the palette. You don't have to reduce it down to only one pixel of each color, just use it as is. The output image has the same type and maxval as the palette image. PARAMETERS There is one parameter, which is required: The file specification of the input PNM file. OPTIONS -mapfile=palettefilename This names the file that contains the palette image. This option is mandatory. -floyd -fs -nofloyd -nofs These options determine whether Floyd-Steinberg dithering is done. Without Floyd-Steinberg, the selection of output color of a pixel is based on the color of only the corresponding input pixel. With Floyd-Steinberg, multiple input pixels are considered so that the average color of an area tends to stay more the same than without Floyd-Steinberg. For example, if you map an image with a black, gray, gray, and white pixel adjacent, to a palette that contains only black and white, it might result in an output of black, black, white, white. Pixel-by-pixel mapping would instead map both the gray pixels to the same color. Floyd-Steinberg gives vastly better results on images where 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. -fs is a synomym for -floyd. -nofs is a synonym for -nofloyd. The default is -nofloyd. -firstisdefault This tells pnmremap to map any input color that is not in the palette to the first color in the palette (the color of the pixel in the top left corner of the palette image) See DESCRIPTION. If you specify -firstisdefault, the maxval of your input must match the maxval of your palette image. -missingcolor=color This specifies the default color for pnmremap to map to a color in the input image that isn't in the palette. color may or may not be in the palette image; it is part of the palette regardless. If you specify -missingcolor, the maxval of your input must match the maxval of your palette image. -verbose Display helpful messages about the mapping process. SEE ALSO pnmcolormap, pamseq, pnmquant, ppmquantall, pnmdepth, ppmdither, ppmquant, ppm AUTHOR Copyright (C) 1989, 1991 by Jef Poskanzer. Table Of Contents NAME SYNOPSIS DESCRIPTION Examples Palette/Image Type Mismatch PARAMETERS OPTIONS SEE ALSO AUTHOR øppmquant Updated: 22 October 2003 Table Of Contents NAME ppmquant - quantize the colors in a PPM image down to a specified number SYNOPSIS ppmquant [-floyd|-fs] ncolors [ppmfile] ppmquant [-floyd|-fs] [-nofloyd|-nofs] -mapfile mapfile [ppmfile] All options can be abbreviated to their shortest unique prefix. You may use two hyphens instead of one to designate an option. You may use either white space or equals signs between an option name and its value. DESCRIPTION This program is part of Netpbm. ppmquant is obsolete. All it does now is invoke pnmquant or pnmremap. You should use one of those programs in any new program, or if you are modifying an old program, and your program does not have to work with a version of Netpbm before 9.21 (January 2001). ppmquant exists only for name compatibility. pnmquant is fully backward compatible with ppmquant without the -mapfile option; pnmremap is fully backward compatible with ppmquant with the -mapfile option. Except with differences suggested by the syntax synopsis above, ppmquant's function is the same as pnmquant and pnmremap. Before Netpbm 10.19 (November 2003), ppmquant was a completely separate program from pnmquant, and was a bona fide PPM program. That means if you gave it a PGM or PBM image as input, it would process it as if it were PPM and generate a PPM output. Now, since it is really a PNM program, it processes PBM and PGM inputs as what they are and produces the same kind of output. Note: The reason ppmquant was changed in Netpbm 10.19 is that for some time before that, ppmquant had a serious bug that would have been difficult to fix -- it chose the wrong color set. Maintaining two versions of the same code did not make sense. SEE ALSO pnmquant, pnmremap, pnmcolormap, pamseq, ppm AUTHOR Copyright (C) 1989, 1991 by Jef Poskanzer. Table Of Contents NAME SYNOPSIS DESCRIPTION REFERENCES SEE ALSO AUTHOR øpnmquant Updated: 22 October 2003 Table Of Contents NAME pnmquant - quantize the colors in a Netpbm image to a smaller set SYNOPSIS pnmquant [-center|-meancolor|-meanpixel] [-floyd|-fs] [-nofloyd|-nofs] [-spreadbrightness|-spreadluminosity] ncolors [pnmfile] All options can be abbreviated to their shortest unique prefix. You may use two hyphens instead of one to designate an option. You may use either white space or equals signs between an option name and its value. DESCRIPTION This program is part of Netpbm. pnmquant reads a PNM image as input. It chooses ncolors colors to best represent the image, maps the existing colors to the new ones, and writes a PNM image as output. This program is simply a combination of pnmcolormap and pnmremap, where the colors of the input are remapped using a color map which is generated from the colors in that same input. The options have the same meaning as in those programs. See their documentation to understand pnmquant. It is much faster to call pnmcolormap and pnmremap directly than to run pnmquant. You save the overhead of the Perl interpreter and creating two extra processes. pnmquant is just a convenience. pnmquant did not exist before Netpbm 9.21 (January 2001). Before that, ppmquant did the same thing, but only on PPM images. ppmquant continues to exist, but is only a front end (for name compatibility) to pnmquant. SEE ALSO pnmcolormap, pnmremap, ppmquantall, pnmdepth, ppmdither, ppmquant, pnm Table Of Contents NAME SYNOPSIS DESCRIPTION SEE ALSO øppmquantall Updated: 27 July 1990 Table Of Contents NAME ppmquantall - run ppmquant on a bunch of files all at once, so they share a common colormap SYNOPSIS ppmquantall [-ext extension] ncolors ppmfile ... DESCRIPTION This program is part of Netpbm. ppmquantall takes a bunch of PPM images as input, chooses ncolors colors to best represent all of the images, maps the existing colors to the new ones, and overwrites the input files with the new quantized versions. If you don't want to overwrite your input files, use the -ext option. The output files are then named the same as the input files, plus a period and the extension text you specify. Verbose explanation: Let's say you've got a dozen PPMs that you want to display on the screen all at the same time. Your screen can only display 256 different colors, but the PPMs have a total of a thousand or so different colors. For a single PPM you solve this problem with pnmquant; ppmquantall solves it for multiple PPMs. All it does is concatenate them together into one big PPM, run pnmquant on that, and then split it up into little PPMs again. (Note that another way to solve this problem is to pre-select a set of colors and then use pnmremap to separately quantize each PPM to that set.) SEE ALSO pnmquant, pnmremap, pnmcolormap, ppm AUTHOR Copyright (C) 1991 by Jef Poskanzer. Table Of Contents NAME SYNOPSIS DESCRIPTION SEE ALSO AUTHOR øppmrelief Updated: 11 January 1991 Table Of Contents NAME ppmrelief - run a Laplacian relief filter on a PPM image SYNOPSIS ppmrelief [ppmfile] DESCRIPTION This program is part of Netpbm. ppmrelief reads a PPM image as input, does a Laplacian relief filter, and writes a PPM image as output. The Laplacian relief filter is described in "Beyond Photography" by Holzmann, equation 3.19. It's a sort of edge-detection. SEE ALSO pgmbentley, pgmoil, ppm AUTHOR Copyright (C) 1990 by Wilson Bent (whb@hoh-2.att.com) Table Of Contents NAME SYNOPSIS DESCRIPTION SEE ALSO AUTHOR øpamfunc Updated: June 2002 Table Of Contents NAME pamfunc - Apply simple arithmetic functions to a Netpbm image SYNOPSIS pamfunc { -multiplier=realnum | -divisor=realnum | -adder=integer | -subtractor=integer | -min=wholenum | -max=wholenum } [filespec] All options can be abbreviated to their shortest unique prefix. You may use two hyphens instead of one. You may separate an option name and its value with white space instead of an equals sign. DESCRIPTION This program is part of Netpbm. pamfunc reads a Netpbm image as input and produces a Netpbm image as output, with the same format, maxval, and dimensions as the input. pamfunc applies a simple transfer function to each sample in the input to generate the corresponding sample in the output. The options determine what function. pamarith is the same thing, except only for PNM images, for binary functions -- it takes two PNM images as input and applies a specified simple arithmetic function (e.g. addition) on pairs of samples from the two to produce the single output image. OPTIONS -multiplier=realnum This option makes the transfer function that of multiplying by realnum. realnum must be nonnegative. If the result is greater than the image maxval, it is clipped to the maxval. Where the input is a PGM or PPM image, this has the effect of dimming or brightening it. For a different kind of brightening, see ppmbrighten and ppmflash Also, see ppmdim, which does the same thing as pamfunc -multiplier on a PPM image with a multiplier between 0 and 1, except it uses integer arithmetic, so it may be faster. And ppmfade can generate a whole sequence of images of brightness declining to black or increasing to white, if that's what you want. -divisor=realnum This option makes the transfer function that of dividing by realnum. realnum must be nonnegative. If the result is greater than the image maxval, it is clipped to the maxval. This is the same function as you would get with -multiplier, specifying the multiplicative inverse of realnum. -adder=integer This option makes the transfer function that of adding wholenum. If the result is greater than the image maxval, it is clipped to the maxval. If it is less than zero, it is clipped to zero. -subtractor=integer This option makes the transfer function that of subtracting wholenum. If the result is greater than the image maxval, it is clipped to the maxval. If it is less than zero, it is clipped to zero. This is the same function as you would get with -multiplier, specifying the negative of integer. -min=wholenum This option makes the transfer function that of taking the maximum of the argument and wholenum. I.e the minimum value in the output will be wholenum. If wholenum is greater than the maxval, though, every sample in the output will be maxval. -max=wholenum This option makes the transfer function that of taking the minimum of the argument and wholenum. I.e the maximum value in the output will be wholenum. If wholenum is greater than the maxval, the function is idempotent -- the output is identical to the input. SEE ALSO ppmdim, ppmbrighten, pnmdepth, pamarith, ppmfade, pbm, pbm, HISTORY This program was added to Netpbm in Release 10.3 (June 2002). Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO HISTORY øpamarith Updated: 22 June 2002 Table Of Contents NAME pamarith - perform arithmetic on two Netpbm images SYNOPSIS pamarith -add | -subtract | -multiply | -difference | -minimum | -maximum | -mean | -compare | -and | -or | -nand | -nor | -xor | -shiftleft | -shiftright pamfile1 pamfile2 All options can be abbreviated to their shortest unique prefix. You may use two hyphens instead of one. You may separate an option name and its value with white space instead of an equals sign. DESCRIPTION This program is part of Netpbm. pamarith reads two PBM, PGM, PPM, or PAM images as input. It performs the specified binary arithmetic operation on their sample values and produces an output of a format which is the more general of the two input formats. The two input images must be of the same width and height. The arithmetic is performed on each pair of identically located tuples to generate the identically located tuple of the output. For the purpose of the calculation, it assumes any PBM, PGM, or PPM input image is the equivalent PAM image of tuple type BLACKANDWHITE, GRAYSCALE, or RGB, respectively, and if it produces a PBM, PGM, or PPM output, produces the equivalent of the PAM image which is the result of the calculation. The first pamfile argument identifies the "left" argument image; the second pamfile argument identifies the "right" one. If the output is PAM, the tuple type is the same as the tuple type of the left input image. pamarith performs the arithmetic on each pair of identically located tuples in the two input images. The arithmetic operation is in all cases fundamentally a function from two integers to an integer. The operation is performed on two tuples as follows. The two input images must have the same depth, or one of them must have depth one. pamarith fails if one of these is not the case. If they have the same depth, pamarith simply carries out the arithmetic one sample at a time. I.e. if at a particular position the left input image contains the tuple (s1,s2,...,sN) and the right input image contains the tuple (t1,t2,...tN), and the function is f, then the output image contains the tuple (f(s1,t1),f(s2,t2),...,f(sN,tN)). If one of the images has depth 1, the arithmetic is performed between the one sample in that image and each of the samples in the other. I.e. if at a particular position the left input image contains the tuple (s) and the right input image contains the tuple (t1,t2,...tN), and the function is f, then the output image contains the tuple (f(s,t1),f(s,t2),...,f(s,tN)). Maxval The meanings of the samples with respect to the maxval varies according to the function you select. In PAM images in general, the most usual meaning of a sample (the one that applies when a PAM image represents a visual image), is that it represents a fraction of some maximum. The maxval of the image corresponds to some maximum value (in the case of a visual image, it corresponds to "full intensity."), and a sample value divided by the maxval gives the fraction. For pamarith, this interpretation applies to the regular arithmetic functions: -add, -subtract, -multiply, -difference, -minimum, -maximum, -mean, and -compare. For those, you should think of the arguments and result as numbers in the range [0,1). For example, if the maxval of the left argument image is 100 and the maxval of the right argument image is 200 and the maxval of the output image is 200, and the left sample value in an -add calculation is 50 and the right sample is 60, the actual calculation is 50/100 + 60/200 = 160/200, and the output sample value is 160. For these functions, pamarith makes the output image's maxval the maximum of the two input maxvals, except with -compare, where pamarith uses an output maxval of 2. If the result of a calculation falls outside the range [0, 1), pamarith clips it -- i.e. considers it to be zero or 1-. In many cases, where both your input maxvals are the same, you can just think of the operation as taking place between the sample values directly, with no consideration of the maxval except for the clipping. E.g. an -add of sample value 5 to sample value 8 yields sample value 13. But with -multiply, this doesn't work. Say your two input images have maxval 255, which means the output image also has maxval 255. Consider a location in the image where the input sample values are 5 and 10. You might think the multiplicative product of those would yield 50 in the output. But pamarith carries out the arithmetic on the fractions 5/255 and 10/255. It multiplies those together and then rescales to the output maxval, giving a sample value in the output PAM of 50/255 rounded to the nearest integer: 0. With the bit string operations, the maxval has a whole different meaning. The operations in question are: -and, -or, -nand, -nor, -xor, and -shiftleft, -shiftright. With these, each sample value in one or both input images, and in the output image, represents a bit string, not a number. The maxval tells how wide the bit string is. The maxval must be a full binary count (a power of two minus one, such as 0xff) and the number of ones in it is the width of the bit string. For the dyadic bit string operations (that's everything but the shift functions), the maxvals of the input images must be the same and pamarith makes the maxval of the output image the same. For the bit shift operations, the output maxval is the same as the left input maxval. The right input image (which contains the shift counts) can have any maxval and the maxval is irrelevant to the interpretation of the samples. The sample value is the actual shift count. But it's still required that no sample value exceed the maxval. The Operations Most of the operations are obvious from the option name. -subtract subtracts a value in the right input image from a value in the left input image. -difference calculates the absolute value of the difference. -multiply does an ordinary arithmetic multiplication, but tends to produce nonobvious results because of the way pamarith interprets sample values. See Maxval. -compare produces the value 0 when the value in the left input image is less than the value in the right input image, 1 when the values are equal, and 2 when the left is greater than the right. -and, -nand, -or, -nor, and -xor consider the input and output images to contain bit strings; they compute bitwise logic operations. -shiftleft and -shiftright consider the left input image and output image to contain bit strings. They compute a bit shift operation, with bits falling off the left or right end and zeroes shifting in, as opposed to bits off one end to the other. The right input image sample value is the number of bit positions to shift. Note that the maxval (see Maxval) determines the width of the frame within which you are shifting. Notes If you want to apply a unary function, e.g. "halve", to a single image, use pamfunc. SEE ALSO pamfunc, pnminvert, ppmbrighten, ppmdim, pnmconvol, pnmdepth, pnmpsnr, pnm, pam HISTORY pamarith replaced pnmarith in Netpbm 10.3 (June 2002). In Netpbm 10.3 through 10.8, though, pamarith was not backward compatible because it required the input images to be of the same depth, so you could not multiply a PBM by a PPM as is often done for masking. (It was not intended at the time that pnmarith would be removed from Netpbm -- the plan was just to rewrite it to use pamarith; it was removed by mistake). But starting with Netpbm 10.9 (September 2002), pamarith allows the images to have different depths as long as one of them has depth 1, and that made it backward compatible with pnmarith. The original pnmarith did not have the -mean option. The compare option was added in Netpbm 10.13 (December 2002). The bit string operations were added in Netpbm 10.27 (March 2005). Table Of Contents NAME SYNOPSIS DESCRIPTION MAXVAL THE OPERATIONS NOTES HISTORY SEE ALSO AUTHOR øpamsummcol Updated: 07 February 2004 Table Of Contents NAME pamsummcol - Sum the columns in a Netpbm image SYNOPSIS pamsummcol { -sum | -mean | -min | -max } [imagefile] All options can be abbreviated to their shortest unique prefix. You may use two hyphens instead of one. You may separate an option name and its value with white space instead of an equals sign. DESCRIPTION This program is part of Netpbm. pamsummcolreads a Netpbm image (PNM or PAM) and performs a summary function over all the rows in each column (sum, mean, etc.). It produces an image of the same kind that the same width and depth as the input, and one row high. Its sample values are the result of the summary. pamsummcol performs the summary operation on each plane independently. pamsummcol performs the operation on the actual sample values, not on the light intensities represented by them in the case that the image is a PGM or PPM image. If you want to summarize by row instead of by column, run the input through pamflip first (and if you want the output to be a single column instead of a single row, use pamflip again). If you want to summarize over the entire image instead of over columns separately, use pamsumm. pamsummcol performs the operation on the actual sample values, not on the light intensities represented by them in the case that the image is a PGM or PPM image or PAM equivalent. You can use pnmgamma to convert such an image to one with samples proportional to light intensity, and then use pamsummcol on the result. You can achieve the same thing as pamsummcol -mean with pamscale. Just scale vertically to a single row, without scaling horizontally at all. Use the pixel mixing method. OPTIONS You must specify exactly one of -sum, -mean, -min, or -max. -sum This option makes the summary function addition. In each column and plane of the output row, the sample value is the sum of all the samples values in the same column and plane of the input. If a result is greater than the image maxval, it is clipped to the maxval. -mean This option makes the summary function arithmetic mean. In each column and plane of the output row, the sample value is the mean of all the samples values in the same column and plane of the input. -min This option makes the summary function arithmetic minimum. In each column and plane of the output row, the sample value is the minimum of all the samples values in the same column and plane of the input. -max This option makes the summary function arithmetic maximum. In each column and plane of the output row, the sample value is the maximum of all the samples values in the same column and plane of the input. SEE ALSO pamsumm, pamscale, pamfunc, pamarith, pamscale, pam, HISTORY pamsummcol was added to Netpbm in Release 10.21 (March 2004). Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO HISTORY øpnmcat Updated: 12 March 1989 Table Of Contents NAME pnmcat - concatenate Netpbm images SYNOPSIS pnmcat {-leftright | -lr | -topbottom | -tb} [-white|-black] [-jtop|-jbottom|-jcenter] pnmfile ... Minimum unique abbreviation of option is acceptable. You may use double hypens instead of single hyphen to denote options. You may use white space in place of the equals sign to separate an option name from its value. DESCRIPTION This program is part of Netpbm. pnmcat reads one or more PNM images as input, concatenates them either left to right or top to bottom, and produces a single PNM image as output. To do the reverse, you might use pamdice to split an image up into smaller ones of equal size or pamcut to chop off part of an image or extract part of an image. pnmtile concatenates a single input image to itself repeatedly. OPTIONS If the PNM images are not all the same height (left-right) or width (top-bottom), the smaller ones have to be justified with the largest. By default, pnmcat centers them, but you can specify justification to one side or the other with one of the -jxxx options. So, -topbottom -jleft would stack the PNMs on top of each other, flush with the left edge. The -white and -black options specify what color to use to fill in the extra space when doing this justification. If neither is specified, pnmcat chooses whichever seems to be right for the images. SEE ALSO pamdice, pnmtile, pamcut, pnm AUTHOR Copyright (C) 1989 by Jef Poskanzer. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO AUTHOR øpnmpad Updated: 26 January 2002 Table Of Contents NAME pnmpad - add borders to a PNM image SYNOPSIS pnmpad [-verbose] [-white|-black] [-width=pixels] [-halign=ratio] [-left=pixels] [-right=pixels] [-height=pixels] [-valign=ratio] [-top=pixels] [-bottom=pixels] [pnmfile] All options can be abbreviated to their shortest unique prefix. You may use two hyphens instead of one to designate an option. You may use either white space or an equals sign between an option name and its value. DESCRIPTION This program is part of Netpbm. pnmpad reads a PNM image as input and outputs a PNM image that is the input image plus black or white borders of the sizes specified. If you just need to convert an image to a certain size regardless of the original dimensions, pamcut with the -pad option may be a better choice. OPTIONS -verbose Verbose output. -white -black Set pad color. Default is -black. -left=pixels -right=pixels -width=width -halign=ratio Specify amount of left and right padding in pixels. -left and -right directly specify the amount of padding added to the left and right sides, respectively, of the image. Alternatively, you can specify -width and just one of -left and -right and pnmpad calculates the required padding on the other side based on the width of the input image. If the -width value is less than the width of the image plus the specified padding, the -width values is ignored. If you specify all three of -width, -left, and -right, you must ensure that the -left and -right padding are sufficient to make the image at least as wide as -width specifies. Otherwise, pnmpad fails. When you specify -width without -left or -right, and -width is larger than the input image, pnmpad chooses left and right padding amounts in a certain ratio. That ratio defaults to half, but you can set it to anything (from 0 to 1) with the -halign option. If the input image is already at least as wide as -width specifies, pnmpad adds no padding. Common values for -halign are: 0.0 left aligned 0.5 center aligned (default) 1.0 right aligned Before Netpbm 10.23 (July 2004), pnmpad did not allow the -left or -right option together with -width. -top=pixels -bottom=pixels -height=height -valign=ratio These options determine the vertical padding. They are analogous to the horizontal padding options above. HISTORY Before February 2002, pnmpad had a different option syntax which was less expressive and not like conventional Netpbm programs. That syntax is still understood by pnmpad for backward compatibility, but not documented or supported for future use. SEE ALSO pbmmake, pnmpaste, pamcut, pnmcrop, pbm AUTHOR Copyright (C) 2002 by Martin van Beilen 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 documentation. This software is provided "as is" without express or implied warranty. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS HISTORY SEE ALSO AUTHOR øpamcomp Updated: 17 July 2004 Table Of Contents NAME pamcomp - composite (overlay) two Netpbm images together SYNOPSIS pamcomp [-align={left|center|right| beyondleft|beyondright}] [-valign={top|middle|bottom| above|below}] [-xoff=X] [-yoff=Y] [-alpha=alpha-pgmfile] [-invert] [-opacity=opacity] [-linear] overlay_file [underlying_file [output_file]] Minimum unique abbreviation of option is acceptable. You may use double hyphens instead of single hyphen to denote options. You may use white space in place of the equals sign to separate an option name from its value. DESCRIPTION This program is part of Netpbm. pamcomp reads two images and produces a composite image with one of the images overlayed on top of the other, possible translucently. The images need not be the same size. The input and outputs are Netpbm format image files. In its simplest use, pamcomp simply places the image in the file overlay_file on top of the image in the file underlying_file, blocking out the part of underlying_file beneath it. If you add the -alpha option, then pamcomp uses the image in file alpha-pgmfile as an alpha mask, which means it determines the level of transparency of each point in the overlay image. The alpha mask must have the same dimensions as the overlay image. In places where the alpha mask defines the overlay image to be opaque, the composite output contains only the contents of the overlay image; the underlying image is totally blocked out. In places where the alpha mask defines the overlay image to be transparent, the composite output contains none of the overlay image; the underlying image shows through completely. In places where the alpha mask shows a value in between opaque and transparent (translucence), the composite image contains a mixture of the overlay image and the underlying image and the level of translucence determines how much of each. The alpha mask is a PGM file in which a white pixel represents opaqueness and a black pixel transparency. Anything in between is translucent. (Like any Netpbm program, pamcomp will see a PBM file as if it is PGM). If the overlay image is a PAM image of tuple type RGB_ALPHA or GRAYSCALE_ALPHA, then the overlay image contains transparency information itself and pamcomp uses it the same way as the alpha mask described above. If you supply both an overlay image that has transparency information and an alpha mask, pamcomp multiplies the two opacities to get the opacity of the overlay pixel. Before Netpbm 10.25 (October 2004), pamcomp did not recognize the transparency information in a PAM image -- it just ignored it. So people had to make appropriate alpha masks in order to have a non-opaque overlay. Some Netpbm programs that convert from image formats such as PNG that contain transparency information are not able to create RGB_ALPHA or GRAYSCALE_ALPHA PAM output, so you have to use the old method -- extract the transparency information from the original into a separate alpha mask and use that as input to pamcomp. The output image is always of the same dimensions as the underlying image. pamcomp uses only parts of the overlay image that fit within the underlying image. To specify where on the underlying image to place the overlay image, use the -align, -valign, -xoff, and -yoff options. Without these options, the default horizontal position is flush left and the default vertical position is flush top. The overlay image, in the position you specify, need not fit entirely within the underlying image. pamcomp uses only the parts of the overlay image that appear above the underlying image. It is possible to specify positioning such that none of the overlay image is over the underlying image -- i.e. the overlay is out of frame. If you do that, pamcomp issues a warning. The overlay and underlying images may be of different formats (e.g. overlaying a PBM text image over a full color PPM image) and have different maxvals. The output image has the more general of the two input formats and a maxval that is the least common multiple the two maxvals (or the maximum maxval allowable by the format, if the LCM is more than that). OPTIONS -align=alignment This option selects the basic horizontal position of the overlay image with respect to the underlying image, in syntax reminiscent of HTML. left means flush left, center means centered, and right means flush right. The -xoff option modifies this position. beyondleft means just out of frame to the left -- the right edge of the overlay is flush with the left edge of the underlying image. beyondright means just out of frame to the right. These alignments are useful only if you add a -xoff option. These two values were added in Netpbm 10.10 (October 2002). The default is left. -valign=alignment This option selects the basic vertical position of the overlay image with respect to the underlying image, in syntax reminiscent of HTML. top means flush top, middle means centered, and bottom means flush bottom. The -yoff option modifies this position. above means just out of frame to the top -- the bottom edge of the overlay is flush with the top edge of the underlying image. below means just out of frame to the bottom. These alignments are useful only if you add a -yoff option. These two values were added in Netpbm 10.10 (October 2002). The default is top. -xoff=x This option modifies the horizontal positioning of the overlay image with respect to the underlying image as selected by the -align option. pamcomp shifts the overlay image from that basic position x pixels to the right. x can be negative to indicate shifting to the left. The overlay need not fit entirely (or at all) on the underlying image. pamcomp uses only the parts that lie over the underlying image. Before Netpbm 10.10 (October 2002), -xoff was mutually exclusive with -align and always measured from the left edge. -yoff=y This option modifies the vertical positioning of the overlay image with respect to the underlying image as selected by the -valign option. pamcomp shifts the overlay image from that basic position y pixels downward. y can be negative to indicate shifting upward. The overlay need not fit entirely (or at all) on the underlying image. pamcomp uses only the parts that lie over the underlying image. Before Netpbm 10.10 (October 2002), -xoff was mutually exclusive with -valign and always measured from the top edge. -alpha=alpha-pgmfile This option names a file that contains the alpha mask. If you don't specify this option, there is no alpha mask, which is equivalent to having an alpha mask specify total opaqueness everywhere. You can specify - as the value of this option and the alpha mask will come from Standard Input. If you do this, don't specify Standard Input as the source of any other input image. -invert This option inverts the sense of the values in the alpha mask, which effectively switches the roles of the overlay image and the underlying image in places where the two intersect. -opacity=opacity This option tells how opaque the overlay image is to be, i.e. how much of the composite image should be from the overlay image, as opposed to the underlying image. opacity is a floating point number, with 1.0 meaning the overlay image is totally opaque and 0.0 meaning it is totally transparent. The default is 1.0. If you specify an alpha mask (the -alpha option), pamcomp uses the product of the opacity indicated by the alpha mask (as modified by the -invert option, as a fraction, and this opacity value. The -invert option does not apply to this opacity value. As a simple opacity value, the value makes sense only if it is between 0 and 1, inclusive. However, pamcomp accepts all values and performs the same arithmetic computation using whatever value you provide. An opacity value less than zero means the underlay image is intensified and then the overlay image is "subtracted" from it. An opacity value greater than unity means the overlay image is intensified and the underlaying image subtracted from it. In either case, pamcomp clips the resulting color component intensities so they are nonnegative and don't exceed the output image's maxval. This may seem like a strange thing to do, but it has uses. You can use it to brighten or darken or saturate or desaturate areas of the underlaying image. See this description of the technique. This option was added in Netpbm 10.6 (July 2002). Before Netpbm 10.15 (April 2003), values less than zero or greater than unity were not allowed. -linear This option indicates that the inputs are not true Netpbm images but rather a non-gamma-adjusted variation. This is relevant only when you mix pixels, using the -opacity option or an alpha mask (the -alpha option). The alpha mask and -opacity values indicate a fraction of the light intensity of a pixel. But the PNM and PNM-equivalent PAM image formats represent intensities with gamma-adjusted numbers that are not linearly proportional to intensity. So pamcomp, by default, performs a calculation on each sample read from its input and each sample written to its output to convert between these gamma-adjusted numbers and internal intensity-proportional numbers. Sometimes you are not working with true PNM or PAM images, but rather a variation in which the sample values are in fact directly proportional to intensity. If so, use the -linear option to tell pamcomp this. pamcomp then will skip the conversions. The conversion takes time. And the difference between intensity-proportional values and gamma-adjusted values may be small enough that you would barely see a difference in the result if you just pretended that the gamma-adjusted values were in fact intensity-proportional. So just to save time, at the expense of some image quality, you can specify -linear even when you have true PPM input and expect true PPM output. For the first 13 years of Netpbm's life, until Netpbm 10.20 (January 2004), pamcomp's predecessor pnmcomp always treated the PPM samples as intensity-proportional even though they were not, and drew few complaints. So using -linear as a lie is a reasonable thing to do if speed is important to you. Another technique to consider is to convert your PNM image to the linear variation with pnmgamma, run pamcomp on it and other transformations that like linear PNM, and then convert it back to true PNM with pnmgamma -ungamma. pnmgamma is often faster than pamcomp in doing the conversion. SEE ALSO ppmmix and pnmpaste are simpler, less general versions of the same tool. ppmcolormask and pbmmask can help with generating an alpha mask. pnmcomp is an older program that runs faster, but has less function. pnm HISTORY pamcomp was new in Netpbm 10.21 (March 2004). Its predecessor, pnmcomp, was one of the first programs added to Netpbm when the project went global in 1993. AUTHOR Copyright (C) 1992 by David Koblas (koblas@mips.com). Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO HISTORY AUTHOR øpnmcomp Updated: 15 February 2004 Table Of Contents NAME pnmcomp - composite (overlay) two PNM images together SYNOPSIS pnmcomp [-align={left|center|right| beyondleft|beyondright}] [-valign={top|middle|bottom| above|below}] [-xoff=X] [-yoff=Y] [-alpha=alpha-pgmfile] [-invert] [-opacity=opacity] overlay_file [underlying_file [output_file]] Minimum unique abbreviation of option is acceptable. You may use double hyphens instead of single hyphen to denote options. You may use white space in place of the equals sign to separate an option name from its value. DESCRIPTION This program is part of Netpbm. pnmcomp was obsoleted by pamcomp, introduced with Netpbm 10.21 (March 2004). pamcomp is backward compatible with pnmcomp, plus adds many additional functions, including the ability to process PAM images, and tends to produce better transparency results. pnmcomp remains in the Netpbm package because it probably has fewer bugs for now than pamcomp, and is faster. Some day, pnmcomp will probably become an alias for pamcomp. You can use the pamcomp documentation for pnmcomp, considering the following differences: pnmcomp options are a subset of pamscale's, as documented above. pnmcomp always assumes the input is linear, as pamcomp does when you specify its -linear option. pnmcomp cannot process PAM images. øppmmix Updated: 16 November 1993 Table Of Contents NAME ppmmix - blend together two PPM images SYNOPSIS ppmmix fadefactor ppmfile1 ppmfile2 DESCRIPTION This program is part of Netpbm. ppmmix reads two PPM images as input and 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 specifies a smooth blend between the two images. The two pixmaps must have the same size. pamcomp is a more general alternative. It allows you to mix images of different size and to have the fade factor vary throughout the image (through the use of an alpha mask). SEE ALSO pamcomp, ppm AUTHOR Copyright (C) 1993 by Frank Neumann Table Of Contents NAME SYNOPSIS DESCRIPTION SEE ALSO AUTHOR øpnmcrop Updated: 18 March 2001 Table Of Contents NAME pnmcrop - crop a PNM image SYNOPSIS pnmcrop [-white|-black|-sides] [-left] [-right] [-top] [-bottom] [pnmfile] All options may be abbreviated to their shortest unique prefix or specified with double hyphens. DESCRIPTION This program is part of Netpbm. pnmcrop reads a PBM, PGM, or PPM image as input, removes borders that are the background color, and produces the same type of image as output. If you don't specify otherwise, pnmcrop assumes the background color is whatever color the top left and right corners of the image are and if they are different colors, something midway between them. You can specify that the background is white or black with the -white and -black options or make pnmcrop base its guess on all four corners instead of just two with -sides. By default, pnmcrop chops off any stripe of background color it finds, on all four sides. You can tell pnmcrop to remove only specific borders with the -left, -right, -top, and -bottom options. If you want to chop a specific amount off the side of an image, use pamcut. If you want to add different borders after removing the existing ones, use pnmcat or pamcomp. OPTIONS -white Take white to be the background color. pnmcrop removes borders which are white. -black Take black to be the background color. pnmcrop removes borders which are black. -sides Determine the background color from the colors of the four corners of the input image. pnmcrop removes borders which are of the background color. If at least three of the four corners are the same color, pnmcrop takes that as the background color. If not, pnmcrop looks for two corners of the same color in the following order, taking the first found as the background color: top, left, right, bottom. If all four corners are different colors, pnmcrop assumes an average of the four colors as the background color. The -sides option slows pnmcrop down, as it reads the entire image to determine the background color in addition to the up to three times that it would read it without -sides. -left Remove any left border. -right Remove any right border. -top Remove any top border. -bottom Remove any bottom border. -verbose Print on Standard Error information about the processing, including exactly how much is being cropped off of which sides. SEE ALSO pamcut, pamfile, pnm AUTHOR Copyright (C) 1989 by Jef Poskanzer. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO AUTHOR øpamcut Updated: 28 February 2005 Table Of Contents NAME pamcut - cut a rectangle out of a PAM, PBM, PGM, or PPM image SYNOPSIS pamcut [-left leftcol] [-right rightcol] [-top toprow] [-bottom bottomrow] [-width width] [-height height] [-pad] [-verbose] [left top width height] [pnmfile] Minimum unique abbreviation of option is acceptable. You may use double hypens instead of single hyphen to denote options. You may use white space in place of the equals sign to separate an option name from its value. DESCRIPTION This program is part of Netpbm. pamcut reads a PAM, PBM, PGM, or PPM image as input and extracts the specified rectangle, and produces the same kind of image as output. There are two ways to specify the rectangle to cut: arguments and options. Options are easier to remember and read, more expressive, and allow you to use defaults. Arguments were the only way available before July 2000. If you use both options and arguments, the two specifications get mixed in an unspecified way. To use options, just code any mixture of the -left, -right, -top, -bottom, -width, and -height options. What you don't specify defaults. It is an error to overspecify, i.e. to specify all three of -left, -right, and -width or -top, -bottom, and -height. To use arguments, specify all four of the left, top, width, and height arguments. left and top have the same effect as specifying them as the argument of a -left or -top option, respectively. width and height have the same effect as specifying them as the argument of a -width or -height option, respectively, where they are positive. Where they are not positive, they have the same effect as specifying one less than the value as the argument to a -right or -bottom option, respectively. (E.g. width = 0 makes the cut go all the way to the right edge). Before July 2000, negative numbers were not allowed for width and height. Input is from Standard Input if you don't specify the input file pnmfile. Output is to Standard Output. If you are splitting a single image into multiple same-size images, pamdice is faster than running pamcut multiple times. pamcomp is also useful for cutting and padding an image to a certain size. You create a background image of the desired frame dimensions and overlay the subject image on it. OPTIONS -left The column number of the leftmost column to be in the output. If a nonnegative number, it refers to columns numbered from 0 at the left, increasing to the right. If negative, it refers to columns numbered -1 at the right, decreasing to the left. -right The column number of the rightmost column to be in the output, numbered the same as for -left. -top The row number of the topmost row to be in the output. If a nonnegative number it refers to rows numbered from 0 at the top, increasing downward. If negative, it refers to columns numbered -1 at the bottom, decreasing upward. -bottom The row number of the bottom-most row to be in the output, numbered the same as for -top. -width The number of columns to be in the output. Must be positive. -height The number of rows to be in the output. Must be positive. -pad If the rectangle you specify is not entirely within the input image, pamcut fails unless you also specify -pad. In that case, it pads the output with black up to the edges you specify. You can use this option if you need to have an image of certain dimensions and have an image of arbitrary dimensions. pnmpad also adds borders to an image, but you specify their width directly. pamcomp does a more general form of this padding. Create a background image of the frame dimensions and overlay the subject image on it. You can use options to have the subject image in the center of the frame or against any edge and make the padding any color (the padding color is the color of the background image). -verbose Print information about the processing to Standard Error. SEE ALSO pnmcrop, pamcomp, pnmpad, pnmcat, pgmslice, pnm HISTORY pamcut was derived from pnmcut in Netpbm 9.20 (May 2001). It was the first Netpbm program adapted to the new PAM format and programming library. The predecessor pnmcut was one of the oldest tools in the Netpbm package. AUTHOR Copyright (C) 1989 by Jef Poskanzer. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO AUTHOR øpnmcut Updated: 15 March 2004 Table Of Contents NAME pnmcut - cut a rectangle out of a PBM, PGM, or PPM image SYNOPSIS pnmcut [-left leftcol] [-right rightcol] [-top toprow] [-bottom bottomrow] [-width width] [-height height] [-pad] [-verbose] [left top width height] [pnmfile] Minimum unique abbreviation of option is acceptable. You may use double hyphens instead of single hyphen to denote options. You may use white space in place of the equals sign to separate an option name from its value. DESCRIPTION This program is part of Netpbm. pnmcut was obsoleted by pamcut, introduced with Netpbm 9.20 (May 2001). pamcut is backward compatible with pnmcut, plus adds many additional functions, including the ability to process PAM images. pnmcut remains in the Netpbm package because it probably has fewer bugs for now than pamcut. Some day, pnmcut will probably become an alias for pamcut. You can use the pamcut documentation for pnmcut, as long as you avoid any function which it says was added after Netpbm 9.20. øpamdice Updated: 31 January 2002 Table Of Contents NAME pamdice - slice a Netpbm image into many horizontally and/or vertically SYNOPSIS pamdice -outstem=filenamestem [-width=width] [-height=height] [-hoverlap=hoverlap] [-voverlap=voverlap] [-verbose] [filename] You can use the minimum unique abbreviation of the options. You can use two hyphens instead of one. You can separate an option name from its value with white space instead of an equals sign. DESCRIPTION This program is part of Netpbm. pamdice reads a PAM, PBM, PGM, or PPM image as input and splits it horizontally and/or vertically into equal size pieces and writes them into separate files as the same kind of image. You can optionally make the pieces overlap. See the -outstem option for information on naming of the output files. The -width and -height options determine the size of the output pieces. pnmcat can rejoin the images. One use for this is to make pieces that take less computer resources than the whole image to process. For example, you might have an image so large that an image editor can't read it all into memory or processes it very slowly. With pamdice, you can split it into smaller pieces, edit one a time, and then reassemble them. Another use for this is to print a large image in small printer-sized pieces that you can glue together. ppmglobe does a similar thing; it lets you glue the pieces together into a sphere. OPTIONS -outstem=filenamestem This option determines the names of the output files. Each output file is named filenamestem_y_x.type where filenamestem is the value of the -outstem option, x and y are the horizontal and vertical locations, respectively, in the input image of the output image, zero being the leftmost and top, and type is .pbm, .pgm, .ppm, or .pam, depending on the type of image. -width=width gives the width in pixels of the output images. The rightmost pieces are smaller than this if the input image is not a multiple of width pixels wide. -height=height gives the height in pixels of the output images. The bottom pieces are smaller than this if the input image is not a multiple of height pixels high. -hoverlap=hoverlap gives the horizontal overlap in pixels between output images. Each image in a row will overlap the previous one by hoverlap pixels. By default, there is no overlap. This option was new in Netpbm 10.23 (July 2004). -voverlap=voverlap gives the vertical overlap in pixels between output images. Each row of images will overlap the previous row by voverlap pixels. By default, there is no overlap. This option was new in Netpbm 10.23 (July 2004). -verbose Print information about the processing to Standard Error. SEE ALSO pamcut, pnmcat, pgmslice, ppmglobe pnm pnm Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO øpamdeinterlace Updated: 11 November 2001 Table Of Contents NAME pamdeinterlace - remove every other row from a PAM/PNM image SYNOPSIS pamdeinterlace [-takeodd] [-takeeven] N [infile] You can use the minimum unique abbreviation of the options. You can use two hyphens instead of one. You can separate an option name from its value with white space instead of an equals sign. DESCRIPTION This program is part of Netpbm. pamdeinterlace removes all the even-numbered or odd-numbered rows from the input PNM or PAM image. Specify which with the -takeeven and -takeodd options. This can be useful if the image is a video capture from an interlaced video source. In that case, each row shows the subject 1/60 second before or after the two rows that surround it. If the subject is moving, this can detract from the quality of the image. Because the resulting image is half the height of the input image, you will then want to use pamstretch or pamscale to restore it to its normal height: pamdeinterlace myimage.ppm | pamstretch -yscale=2 >newimage.ppm OPTIONS -takeodd Take the odd-numbered rows from the input and put them in the output. The rows are numbered starting at zero, so the first row in the output is the second row from the input. You cannot specify both -takeeven and -takeodd. -takeeven Take the even-numbered rows from the input and put them in the output. The rows are numbered starting at zero, so the first row in the output is the first row from the input. This is the default. You cannot specify both -takeeven and -takeodd. SEE ALSO pamstretch, pamscale Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO øpnmstitch Updated: July 2002 Table Of Contents NAME pnmstitch - stitch together two panoramic (side-by-side) photographs SYNOPSIS pnmstitch [ [left_filespec] right_filespec | left_filespec right_filespec output_filespec ] [-width=width] [-height=height] [-xrightpos=column] [-yrightpos=row] [-stitcher={RotateSliver, BiLinearSliver,LinearSliver}] [-filter={LineAtATime,HorizontalCrop}] [-output=output_filespec] [-verbose] All options can be abbreviated to their shortest unique prefix. You may use two hyphens instead of one. You may separate an option name and its value with white space instead of an equals sign. DESCRIPTION This program is part of Netpbm. pnmstitch stitches together two panoramic photographs. This means if you have photographs of the left and right side of something that is too big for a single camera frame, pnmstitch can join them into one wide picture. pnmstitch works only on side-by-side images, not top and bottom (though you could certainly use pnmrotate in combination with pnmstitch to achieve this). It stitches together two images, but you can use it repeatedly to stitch together as many as you need to. Your photographs must overlap in order for pnmstitch to work, and the overlap should be substantial. pnmstitch shifts and stretches the right hand image to match it up the left hand image. You probably want to crop the result with pamcut to make a nice rectangular image. If you're just trying to join (concatenate) two images at their edges, use pnmcat. The left_filespec and right_filespec arguments are the specifications (names) of the PNM files containing the left hand and right hand images. If you specify only right_filespec, the left hand image comes from Standard Input. If you specify neither, both images come from Standard Input as a multi-image file containing first the left and then the right image. output_filespec is the specification (name) of the output PNM file. The -output option also specifies the output file. You cannot specify both the argument and the option. If you specify neither, the output goes to Standard Output. OPTIONS -width=width -height=height -xrightpos=column -yrightpos=row These are constraints on where pnmstitch stitches the images together. For the LinearSliver method, column and row tell what location in the right hand image matches up to the top right corner of the left hand image. -stitcher={RotateSliver,BiLinearSliver, LinearSliver} The default is RotateSliver. -filter={LineAtATime,HorizontalCrop} No details available. -output=output_filespec Name of output file. If you don't specify this option, the output image goes to Standard Output. -verbose This option causes pnmstitch to issue messages to Standard Error about the stitching process. SEE ALSO pamcut, pnmcat, pnmrotate, pnm, HISTORY This program was added to Netpbm in Release 10.7 (August 2002). Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO HISTORY øppmglobe Updated: 10 May 2003 Table Of Contents NAME ppmglobe - generate strips to glue onto a sphere SYNOPSIS ppmglobe stripcount DESCRIPTION This program is part of Netpbm. ppmglobe does the inverse of a cylindrical projection of a sphere. Starting with a cylindrical projection, it produces an image you can cut up and glue onto a sphere to obtain the spherical image of which it is the cylindrical projection. What is a cylindrical projection? Imagine a map of the Earth on flat paper. There are lots of different ways cartographers show the three dimensional information in such a two dimensional map. The cylindrical projection is one. You could make a cylindrical projection by putting a light inside a globe and wrapping a rectangular sheet of paper around the globe, touching the globe at the Equator. Then trace the image that the light projects onto the paper. Lay the paper out flat and you have a cylindrical projection. Here's where ppmglobe comes in: Pass the image on that paper through ppmglobe and what comes out the other side looks something like this: If the input is PBM, pnmhistmap produces an error message and no output image. OPTIONS -red -green -blue Include the indicated color component in the output. If you specify none of these, pnmhistmap include all three. These options are meaningless if the input is PGM. These options were new in Netpbm 10.26 (January 2005). Before that, pnmhistmap always included all three color components. -dots Plot the histogram as dots. By default, pnmhistmap plots bars. Example of dots: FPRIVATE "TYPE=PICT;ALT=-dots example" This option was new in Netpbm 10.26 (January 2005). Before that, pnmhistmap always plotted bars. -lval minpixval -rval maxpixval These options specify the range of intensity values to include. pnmhistmap ignores intensities less than minpixval and greater than maxpixval. So the left side of the histogram corresponds to minpixval and the right side corresponds to maxpixval. By default, pnmhistmap plots the entire possible range: zero to the maxval. These options were new in Netpbm 10.26 (January 2005). Before that, pnmhistmap always plotted from zero to the maxval. -height -width These options specify the dimensions, in pixels of the histogram image. The default height is 200 pixels. The default width is one pixel for each plotted intensity value (so it's controlled by the maxval of the image and the -lval and -rval options). The "count buckets" in the histogram are always one pixel wide. If you specify a width less than the number of plotted intensity values, a bucket represents more than one intensity value. If you specify a width greater that the number of plotted intensity values, some buckets represent no color (the count is zero). This option was new in Netpbm 10.26 (January 2005). Before that, the dimensions were always what the default is today. -black Ignore the count of black pixels when scaling the histogram. -white Ignore the count of white pixels when scaling the histogram. The -black and -white options, which can be used separately 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. LIMITATIONS pnmhistmap assumes maxval is always 255. Images with a smaller maxval will only use the lower-value side of the histogram. You can overcome this either by piping the input through pnmdepth or by cutting and scaling the lower-value side of the histogram. Neither is a particularly elegant solution to the problem. The program does not allow you to specify the output size. SEE ALSO pgmhist, ppmhist, pgm, ppm AUTHOR Wilson H. Bent. Jr. (whb@usc.edu). Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS BUGS SEE ALSO AUTHOR øpnmcolormap Updated: 12 December 2001 Table Of Contents NAME pnmcolormap - create quantization color map for a Netpbm image SYNOPSIS pnmcolormap [-center|-meancolor|-meanpixel] [-spreadbrightness|-spreadluminosity] [-sort] [-square] ncolors|all [pnmfile] All options can be abbreviated to their shortest unique prefix. You may use two hyphens instead of one to designate an option. You may use either white space or an equals sign between an option name and its value. DESCRIPTION This program is part of Netpbm. pnmcolormap reads a PNM image as input, chooses ncolors colors to best represent the image, maps the existing colors to the new ones, and writes a PNM color map defining them as output. You can use this map as input to pnmremap on the same input image to quantize the colors in that image, I.e. produce a similar image with fewer colors. pnmquant does both the pnmcolormap and pnmremap steps for you. A PNM colormap is a PNM image of any dimensions that contains at least one pixel of each color in the set of colors it represents. The quantization method is Heckbert's "median cut". See QUANTIZATION METHOD. If the input image is a PPM, the output image is a PPM. If the input image is a PBM or PGM, the output colormap is a PGM. Note that a colormap of a PBM image is not very interesting. The colormap generally has the same maxval as the input image, but pnmcolormap may reduce it if there are too many colors in the input, as part of its quantization algorithm. If you want to create a colormap without basing it on the colors in an input image, see ppmcolors. PARAMETERS The single parameter, which is required, is the number of colors you want in the output colormap. pnmcolormap may produce a color map with slightly fewer colors than that. You may specify all to get a colormap of every color in the input image (no quantization). OPTIONS -sort This option causes the output colormap to be sorted by the red component intensity, then the green, then the blue in ascending order. This is an insertion sort, so it is not very fast on large colormaps. Sorting is useful because it allows you to compare two sets of colors. -square By default, pnmcolormap produces as the color map a PPM image with one row and one column for each color in the colormap. This option causes pnmcolormap instead to produce a PPM image that is within one row or column of being square, with multiple pixels of the same color as necessary to create a number of pixels which is a perfect square. -verbose This option causes pnmcolormap to display messages to Standard Error about the quantization. -center -meancolor -meanpixel -spreadbrightness -spreadluminosity These options control the quantization algorithm. See QUANTIZATION METHOD. QUANTIZATION METHOD A quantization method is a way to choose which colors, being fewer in number than in the input, you want in the output. pnmcolormap uses Heckbert's "median cut" quantization method. This method involves separating all the colors into "boxes," each holding colors that represent about the same number of pixels. You start with one box and split boxes in two until the number of boxes is the same as the number of colors you want in the output, and choose one color to represent each box. When you split a box, you do it so that all the colors in one sub-box are "greater" than all the colors in the other. "Greater," for a particular box, means it is brighter in the color component (red, green, blue) which has the largest spread in that box. pnmcolormap gives you two ways to define "largest spread.": 1) largest spread of brightness; 2) largest spread of contribution to the luminosity of the color. E.g. red is weighted much more than blue. Select among these with the -spreadbrightness and -spreadluminosity options. The default is -spreadbrightness. pnmcolormap provides three ways of choosing a color to represent a box: 1) the center color - the color halfway between the greatest and least colors in the box, using the above definition of "greater"; 2) the mean of the colors (each component averaged separately by brightness) in the box; 3) the mean weighted by the number of pixels of a color in the image. Note that in all three methods, there may be colors in the output which do not appear in the input at all. Select among these with the -center, -meancolor, and -meanpixel options. The default is -center. REFERENCES "Color Image Quantization for Frame Buffer Display" by Paul Heckbert, SIGGRAPH '82 Proceedings, page 297. SEE ALSO pnmremap, pnmquant, ppmquantall, pnmdepth, ppmdither, ppmquant, ppm HISTORY Before Netpbm 10.15 (April 2003), pnmcolormap used a lot more memory for large images because it kept the entire input image in memory. Now, it processes it a row at a time, but because it sometimes must make multiple passes through the image, it first copies the input into a temporary seekable file if it is not already in a seekable file. pnmcolormap first appeared in Netpbm 9.23 (January 2002). Before that, its function was available only as part of the function of pnmquant (which was derived from the much older ppmquant). Color quantization really has two main subfunctions, so Netpbm 9.23 split it out into two separate programs: pnmcolormap and pnmremap and then Netpbm 9.24 replaced pnmquant with a program that simply calls pnmcolormap and pnmremap. AUTHOR Copyright (C) 1989, 1991 by Jef Poskanzer. Table Of Contents NAME SYNOPSIS DESCRIPTION PARAMETERS OPTIONS QUANTIZATION METHOD REFERENCES SEE ALSO HISTORY AUTHOR øpamsharpness Updated: 07 Februrary 2004 Table Of Contents NAME pamsharpness - measure the sharpness of a PNM/PAM image SYNOPSIS pamsharpness [imagefile] DESCRIPTION This program is part of Netpbm. pamsharpnessreads a Netpbm image (PNM or PAM) and prints a number that tells how sharp it is. Sharpness is a measure of how suddenly (in space) colors change in the image. pamsharpness computes the sharpness of the image as the average difference in intensity between each pixel and its 8 surrounding pixels, in each of the color components (R, G, B). pamsharpness does not include the edges of the image, where there are not 8 pixels surrounding a pixel, in its computation. pamsharpness assumes that the image is a PNM or PNM equivalent PAM. If it isn't, the results are not necessarily meaningful. SEE ALSO pamsharpmap, pam, pnm HISTORY pamsharpness was added to Netpbm in Release 10.21 (March 2004). Bryan Henderson derived it from the program pnmsharp by B.W. van Schooten and distributed as part of the Photopnmtools package. Table Of Contents NAME SYNOPSIS DESCRIPTION SEE ALSO HISTORY øpamsharpmap Updated: 07 February 2004 Table Of Contents NAME pamsharpmap - create map of sharpness in a PNM/PAM image SYNOPSIS pamsharpmap [imagefile] DESCRIPTION This program is part of Netpbm. pamsharpmapreads a Netpbm image (PNM or PAM) and produces an image that shows how sharp it is at each location. Sharpness is a measure of how suddenly (in space) colors change in the image. pamsharpmap computes the sharpness of each component color (R, G, B) separately and produces a pixel whose intensity of each component color is directly proportional to the sharpness of that component color at the same location in the input image. Thus, at point where the image is very sharp in its red and green components are very sharp, but dull in its blue component, you will see a yellow pixel in the output. pamsharpmap computes sharpness at a point simply as the average difference in intensity between the pixel at that point and the 8 pixels surrounding it. At the edges of the image, where there are not 8 pixels surrounding a pixel, pamsharpmap assumes the image is extended with a black border. pamsharpmap assumes that the image is a PNM or PNM equivalent PAM. If it isn't, the results are not necessarily meaningful. The output image is the same dimensions, depth, and tuple type as the input, and has maxval 255. SEE ALSO pamsharpness, pamedge, pam, pnm HISTORY pamsharpmap was added to Netpbm in Release 10.21 (March 2004). Bryan Henderson derived it from the program pnmsharp by B.W. van Schooten and distributed as part of the Photopnmtools package. Table Of Contents NAME SYNOPSIS DESCRIPTION SEE ALSO HISTORY øppm3d Updated: 24 April 2004 Table Of Contents NAME ppm3d - convert two PPM images into a red/blue 3d glasses PPM SYNOPSIS ppm3d leftppmfile rightppmfile [horizontal_offset] DESCRIPTION This program is part of Netpbm. ppm3d reads two PPM images as input and produces a PPM as output, with the images overlapping by horizontal_offset pixels in blue/red format. The idea is that if you look at the image with 3-D glasses (glasses that admit only red through one eye and only green through the other), you see an image with depth. This is called a stereogram. horizontal_offset defaults to 30 pixels. The input PPMs must be the same dimensions. To make a different kind of stereogram, use pamstereogram. That makes a steregram that you view without special glasses, just by letting your eyes unfocus so that each eye sees different parts of the image. SEE ALSO pamstereogram ppm AUTHOR Copyright (C) 1993 by David K. Drum. Table Of Contents NAME SYNOPSIS DESCRIPTION SEE ALSO AUTHOR øppmsvgalib Updated: 06 January 2002 Table Of Contents NAME ppmsvgalib - display PPM image on Linux console using Svgalib SYNOPSIS ppmsvgalib [-mode=mode] All options can be abbreviated to their shortest unique prefix. You may use two hyphens instead of one to designate an option. You may use either white space or an equals sign between an option name and its value. DESCRIPTION This program is part of Netpbm. ppmsvgalib displays a PPM image on a Linux virtual console using the Svgalib facility. Svgalib is a popular means of displaying Graphics in Linux without the use of the X Window System. If you run ppmsvgalib with a version of Svgalib earlier than 1.9, you must run it as superuser, as Svgalib uses superuser-only facilities to access the console hardware. Newer Svgalib has its own device driver, so you need only properly permissions on a device special file to access the console. ppmsvgalib is not capable of using color mapped video modes. These are the old video modes that are usually called "8 bit" color modes. ppmsvgalib is a bare displayer. It won't do any manipulation of the image and is not interactive in any way. If you want a regular interactive graphics viewer that uses Svgalib, try zgv (not part of Netpbm). To exit ppmsvgalib while it is displaying your image, send it a SIGINTR signal (normally, this means "hit control C"). ppmsvgalib draws a white border around the edges of the screen. It does this to help you isolate problems between the image you're displaying and the facilities you're using to display it. (Note: if the image you're displaying reaches the edges of the screen, it will replace the white border). ppmsvgalib places the image in the center of the screen. If your image is too big to display in the video mode you selected, ppmsvgalib fails. You can use pamcut to cut out a part of the image to display or use pamscale to shrink the image to fit. If you want to play with ppmsvgalib, ppmcie is a good way to generate a test image. To be pedantic, we must observe that ppmsvgalib displays a PPM image in the correct colors only if the display has a transfer function which is the exact inverse of the gamma function that is specified in the PPM specification. Happily, most CRT displays are pretty close. Running the PPM image through pnmgamma can help cause ppmsvgalib to display the correct colors. OPTIONS -mode=mode This tells ppmsvgalib what video mode to use. mode is the Svgalib video mode number. You can get a list of all the video modes and their Svgalib video mode numbers with the program vgatest that is packaged with Svgalib. (Unfortunately, the various interesting programs that are packaged with Svgalib are typically not installed on systems that have the Svgalib library installed). In practice, there are probably only two modes you'll ever care about: 25 is the standard SVGA direct color mode, which is 1024 columns by 768 rows with 8 bit red, green, and blue components for each pixel and no fancy options. 28 is the same, but with the popular higher resolution of 1280 x 1024. But if you have an older video controller (with less than 4MB of memory), those modes aren't available and you might like mode 19, which is 640 x 480 and takes less than a megabyte of video memory. This is a standard VGA video mode. SEE ALSO pamcut, pamscale, ppmcie, ppm, zgv, Svgalib, vgatest AUTHOR By Bryan Henderson, January 2002. Contributed to the public domain. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO AUTHOR øpbmmask Updated: 08 August 1989 Table Of Contents NAME pbmmask - create a mask bitmap from a regular bitmap SYNOPSIS pbmmask [-expand] [pbmfile] DESCRIPTION This program is part of Netpbm. pbmmask reads a PBM image as input and Generates a corresponding mask of the foreground areas as another PBM image. 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 | pnmpaste -or obj 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 | pnmpaste -or blackback 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 pnmsmooth before using it. This makes the boundary between the two images less sharp. OPTIONS -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 program into a general cellular automaton tool...) SEE ALSO ppmcolormask, pnmpaste, pnminvert, pnmarith, pnmsmooth pbm, AUTHOR Copyright (C) 1988 by Jef Poskanzer. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO AUTHOR øppmcolormask Updated: 14 April 2000 Table Of Contents NAME ppmcolormask - produce mask of areas of a certain color in a PPM file SYNOPSIS ppmcolormask color [ppmfile] DESCRIPTION This program is part of Netpbm. ppmcolormask reads a PPM file as input and produces a PBM (bitmap) file as output. The output file is the same dimensions as the input file and is black in all places where the input file is the color color, and white everywhere else. The output of ppmcolormask is useful as an alpha mask input to pamcomp. Note that you can generate such an alpha mask automatically as you convert to PNG format with pnmtopng. Use its -transparent option. ppmfile is the input file. If you don't specify ppmfile, the input is from Standard Input. The output goes to Standard Output. Specify the color (color) as described for the argument of the ppm_parsecolor() library routine. SEE ALSO pgmtoppm, pamcomp, pbmmask, ppm Table Of Contents NAME SYNOPSIS DESCRIPTION SEE ALSO AUTHOR øpnmsplit Updated: 19 June 2000 Table Of Contents NAME pnmsplit - split a multi-image PNM file into multiple single-image files SYNOPSIS pnmsplit [pnmfile[ output_file_pattern]] [-padname=n] Minimum unique abbreviation of option is acceptable. You may use double hypens instead of single hyphen to denote options. You may use white space in place of the equals sign to separate an option name from its value. DESCRIPTION This program is part of Netpbm. pnmsplit reads a PNM stream as input. It copies each image in the input into a separate file, in the same format. pnmfile is the file specification of the input file, or - to indicate Standard Input. The default is Standard Input. output_file_pattern tells how to name the output files. It is the file specification of the output file, except that the first occurence of "%d" in it is replaced by the image sequence number in unpadded ASCII decimal, with the sequence starting at 0. If there is no "%d" in the pattern, pnmsplit fails. The default output file pattern is "image%d". The -padname option specifies to how many characters you want the image sequence number in the output file name padded with zeroes. pnmpslit adds leading zeroes to the image sequence number to get up to at least that number of characters. This is just the number of characters in the sequence number part of the name. For example, pnmsplit - outputfile%d.ppm -padname=3 would yield output filenames outputfile000.ppm, outputfile001.ppm, etc. The default is no padding (equivalent to -padname=0. The -padname option was new in Netpbm 10.23 (July 2004). Before that, there was never any padding. Note that to do the reverse operation (combining multiple single-image PNM files into a multi-image one), there is no special Netpbm program. Just use cat. SEE ALSO pnm, cat man page Table Of Contents NAME SYNOPSIS DESCRIPTION SEE ALSO øpnmindex Updated: 9 January 1991 Table Of Contents NAME pnmindex - build a visual index of a bunch of PNM images SYNOPSIS pnmindex [-size N] [-across N] [-colors N] [-black] [-title title] [-quant|-noquant] pnmfile... DESCRIPTION This program is part of Netpbm. pnmindex creates an index image containing thumbnail (small) versions of a bunch of PNM files you supply. pnmindex labels each thumbnail and, optionally, contains a title. If you just want to concatenate some images together, use pnmcat for that. If you want to make a grid of the same image repeated over and over, that's pnmtile. If you want to take apart the image you generated with pnmindex, use pamdice or pamcut. OPTIONS -size N The size of each thumbnail. The image is scaled to fit maximally inside a N x N pixel box without changing its aspect ratio. Default is 100. -across N The number of thumbnails in each row. Default is 6. -colors N The maximum number of colors allowed in the overall image. If it would otherwise have more colors than these, pnmindex quantizes the result. The default is 256. However, this value is meaningless if you specify the -noquant option. -black This controls the color of the padding between the images; normally it's white and the labels are black lettering on white background, but the -black option reverses this. -title title Specifies a title top place at the top of the image. Default is no title. -quant Enables quanization (to the number of colors specified by -colors). Quantization is on by default but you can disable it with -noquant. -noquant See -quant. SEE ALSO pnmscale, pnmcat, pbmtext, pnmquant, pnm AUTHOR Copyright (C) 1991 by Jef Poskanzer. -title and -noquant added 2000 by John Heidemann. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO AUTHOR øpnmmontage Updated: 31 December 2000 Table Of Contents NAME pnmmontage - create a montage of PNM images SYNOPSIS pnmmontage [-header=headerfile] [-quality=n] [-prefix=prefix] [-0|-1|-2|...|-9] pnmfile... DESCRIPTION This program is part of Netpbm. pnmmontage packs images of differing sizes into a minimum-area composite image, optionally producing a C header file with the locations of the subimages within the composite image. OPTIONS -header Tells pnmmontage to write a C header file of the locations of the original images within the packed image. Each original image generates four #defines within the packed file: xxxX, xxxY, xxxSZX, and xxxSZY, where xxx is the name of the file, converted to all uppercase. The ouput also includes #defines OVERALLX and OVERALLY, which specifies the total size of the montage image. -prefix Tells pnmmontage to use the specified prefix on all of the #defines it generates. -quality Before attempting to place the subimages, pnmmontage will calculate a minimum possible area for the montage; this is either the total of the areas of all the subimages, or the width of the widest subimage times the height of the tallest subimage, whichever is greater. pnmmontage then initiates a problem-space search to find the best packing; if it finds a solution that is (at least) as good as the minimum area times the quality as a percent, it will break out of the search. Thus, -q 100 will find the best possible solution; however, it may take a very long time to do so. The default is -q 200. -0, -1, ... -9 These options control the quality at a higher level than -q; -0 is the worst quality (literally pick the first solution found), while -9 is the best quality (perform an exhaustive search of problem space for the absolute best packing). The higher the number, the slower the computation. The default is -5. NOTES Using -9 is excessively slow on all but the smallest image sets. If the anymaps differ in maxvals, then pnmmontage will pick the smallest maxval which is evenly divisible by each of the maxvals of the original images. SEE ALSO pnmcat, pnmindex, pnm, pam, pbm, pgm, ppm AUTHOR Copyright (C) 2000 by Ben Olmstead. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS NOTES SEE ALSO AUTHOR øpgmbentley Updated: 11 January 1991 Table Of Contents NAME pgmbentley - Bentleyize a PGM image SYNOPSIS pgmbentley [pgmfile] DESCRIPTION This program is part of Netpbm. pgmbentleyreads a PTM image as input and performs the Bentley Effect, and writes a PGM image as output. The Bentley Effect is described in "Beyond Photography" by Holzmann, chapter 4, photo 4. It's a vertical smearing based on brightness. SEE ALSO pgmoil, ppmrelief, pgm AUTHOR Copyright (C) 1990 by Wilson Bent (whb@hoh-2.att.com) Table Of Contents NAME SYNOPSIS DESCRIPTION SEE ALSO AUTHOR øpgmbentley Updated: 11 January 1991 Table Of Contents NAME pgmbentley - Bentleyize a PGM image SYNOPSIS pgmbentley [pgmfile] DESCRIPTION This program is part of Netpbm. pgmbentleyreads a PTM image as input and performs the Bentley Effect, and writes a PGM image as output. The Bentley Effect is described in "Beyond Photography" by Holzmann, chapter 4, photo 4. It's a vertical smearing based on brightness. SEE ALSO pgmoil, ppmrelief, pgm AUTHOR Copyright (C) 1990 by Wilson Bent (whb@hoh-2.att.com) Table Of Contents NAME SYNOPSIS DESCRIPTION SEE ALSO AUTHOR øpamoil Updated: 25 June 2001 Table Of Contents NAME pamoil - turn a PAM image into an oil painting SYNOPSIS pamoil [-n N] [pamfile] DESCRIPTION This program is part of Netpbm. pamoil reads a Netpbm image as input and does an "oil transfer", and writes the same type of Netpbm image as output. The oil transfer is described in "Beyond Photography" by Holzmann, chapter 4, photo 7. It's a sort of localized smearing. The smearing works like this: First, assume a grayscale image. For each pixel in the image, pamoil looks at a square neighborhood around it. pamoil determines what is the most common pixel intensity in the neighborhood, and puts a pixel of that intensity into the output in the same position as the input pixel. For color images, or any arbitrary multi-channel image, pamoil computes each channel (e.g. red, green, and blue) separately the same way as the grayscale case above. At the edges of the image, where the regular neighborhood would run off the edge of the image, pamoil uses a clipped neighborhood. OPTIONS -n size This is the size of the neighborhood used in the smearing. The neighborhood is this many pixels in all four directions. The default is 3. SEE ALSO pgmbentley, ppmrelief, ppm AUTHOR This program is based on pgmoil Copyright (C) 1990 by Wilson Bent (whb@hoh-2.att.com) Modified to ppm by Chris Sheppard, June 25, 2001 Modified to pnm, using pam functions, by Bryan Henderson June 28, 2001. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS SEE ALSO AUTHOR øppmforge Updated: 25 October 1991 Table Of Contents NAME ppmforge - fractal forgeries of clouds, planets, and starry skies 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] You can abbreviate any options to its shortest unique prefix. DESCRIPTION This program is part of Netpbm. ppmforge generates three kinds of ``random fractal forgeries,'' the term coined by Richard F. Voss of the IBM Thomas J. Watson Research Center for seemingly realistic pictures of natural objects generated by simple algorithms embodying randomness and fractal self-similarity. The techniques used by ppmforge are essentially those given by Voss[1], particularly the technique of spectral synthesis explained in more detail by Dietmar Saupe[2]. The program generates two varieties of pictures: planets and clouds, which are just different renderings of data generated in an identical manner, illustrating the unity of the fractal structure of these very different objects. A third type of picture, a starry sky, is synthesised directly from pseudorandom numbers. The generation of planets or clouds begins with the preparation of an array of random data in the frequency domain. The size of this array, the ``mesh size,'' can be set with the -mesh option; the larger the mesh the more realistic the pictures but the calculation time and memory requirement increases as the square of the mesh size. The fractal dimension, which you can specify with the -dimension option, determines the roughness of the terrain on the planet or the scale of detail in the clouds. As the fractal dimension is increased, more high frequency components are added into the random mesh. Once the mesh is generated, an inverse two dimensional Fourier transform is performed upon it. This converts the original random frequency domain data into spatial amplitudes. We scale the real components that result from the Fourier transform into numbers from 0 to 1 associated with each point on the mesh. You can further modify this number by applying a ``power law scale'' to it with the -power option. Unity scale leaves the numbers unmodified; a power scale of 0.5 takes the square root of the numbers in the mesh, while a power scale of 3 replaces the numbers in the mesh with their cubes. Power law scaling is best envisioned by thinking of the data as representing the elevation of terrain; powers less than 1 yield landscapes with vertical scarps that look like glacially-carved valleys; powers greater than one make fairy-castle spires (which require large mesh sizes and high resolution for best results). After these calculations, we have a array of the specified size containing numbers that range from 0 to 1. The pixmaps are generated as follows: Clouds A color map is created that ranges from pure blue to white by increasing admixture (desaturation) of blue with white. Numbers less than 0.5 are colored blue, numbers between 0.5 and 1.0 are colored 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 colored 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 approximately 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 modulated 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 apparent color of each pixel of the planet is calculated 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 primary 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 generate stars with a user specified density. Cloud pictures always contain 256 or fewer colors and may be displayed on most color mapped devices without further processing. Planet pictures often contain tens of thousands of colors which must be compressed with pnmquant or ppmdither before encoding in a color mapped format. If the display resolution is high enough, ppmdither generally produces better looking planets. pnmquant tends to create discrete color bands, particularly in the oceans, which are unrealistic and distracting. The number of colors in starry sky pictures generated with the -night option depends on the value specified for -saturation. Small values limit the color temperature distribution of the stars and reduce the number of colors in the image. If the -saturation is set to 0, none of the stars will be colored and the resulting image will never contain more than 256 colors. Night sky pictures with many different star colors often look best when color compressed by pnmdepth rather than pnmquant or ppmdither. Try newmaxval settings of 63, 31, or 15 with pnmdepth to reduce the number of colors in the picture to 256 or fewer. 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 resolution 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 extent to which terrain elevation causes ice to appear at lower latitudes. The default value of 0.75 makes the polar caps extend toward the equator 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, ppmforge uses hour 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 center 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 Europa. -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 inclination angle can be thought of as specifying, in degrees, the ``season'' the planet is presently experiencing 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, negative 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 requirements 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 capacity, you may have to reduce the mesh size to avoid running out of RAM. Increasing the mesh size produces better looking pictures; the difference becomes particularly noticeable when generating high resolution images with relatively high fractal dimensions (between 2.2 and 3). -night A starry sky is generated. The stars are created by the same algorithm used for the stars that surround planet pictures, but the output consists exclusively 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 factors 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 color saturation of the stars that surround planet pictures and fill starry skies created with the -night option. The default value of 125 creates stars which resemble the sky as seen by the human eye from Earth's surface. Stars are dim; only the brightest activate the cones in the human retina, causing color 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 color. 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, consequently there are many reddish stars for every blue giant. 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 generated 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 surrounding 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 pamcut 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. LIMITATIONS The algorithms require the output pixmap to be at least as wide as it is high, and the width to be an even number of pixels. These constraints are enforced by increasing the size of the requested pixmap if necessary. You may have to reduce the FFT mesh size on machines with 16 bit integers and segmented pointer architectures. SEE ALSO pamcut, pnmdepth, ppmdither, pnmquant, 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. 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 restrictions. This software is provided ``as is'' without express or implied warranty. PLUGWARE! If you like this kind of stuff, you may also enjoy ``James Gleick's Chaos--The Software'' for MS-DOS, available for $59.95 from your local software store or directly from Autodesk, Inc., Attn: Science Series, 2320 Marinship Way, Sausalito, CA 94965, USA. Telephone: (800) 688-2344 toll-free or, outside the U.S. (415) 332-2344 Ext 4886. Fax: (415) 289-4718. ``Chaos--The Software'' includes a more comprehensive fractal forgery generator which creates three-dimensional landscapes as well as clouds and planets, plus five more modules which explore other aspects of Chaos. The user guide of more than 200 pages includes an introduction by James Gleick and detailed explanations by Rudy Rucker of the mathematics and algorithms used by each program. Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS LIMITATIONS SEE ALSO AUTHOR øpgmkernel Updated: 10 December 1992 Table Contents NAME pgmkernel - generate a convolution kernel SYNOPSIS pgmkernel [-weight w] width [height ] DESCRIPTION This program is part of Netpbm. pgmkernel generates a convolution kernel that you can use with pnmconvol. The kernel is one where the weight of each location is inversely proportional to its distance from the center of the kernel. pgmkernel generates a PGM image of size width by height (or width by width if you don't specify height). pgmkernel computes the convolution function K as follows. K(i,j) = 1 / ( 1 + w * sqrt(i^2 + j^2)) where w is a coefficient specified via the -weight flag. i and j are measured in pixels. K is zero everywhere beyond the specified kernel width and height. pgmkernel generates the output PGM file in the Plain (text) variation of PGM. OPTIONS The optional -weight flag should be a real number greater than -1. The default value is 6.0. LIMITATIONS The computation time is proportional to width*height. This increases rapidly with the increase of the kernel size. A better approach could be using a FFT in these cases. SEE ALSO pnmconvol, pnmsmooth pamgauss pgm AUTHOR Alberto Accomazzi (alberto@cfa.harvard.edu). Table Of Contents NAME SYNOPSIS DESCRIPTION OPTIONS BUGS SEE ALSO AUTHOR øppmtv Updated: 16 November 1993 Table Of Contents NAME ppmtv - make a PPM image look like taken from an American TV SYNOPSIS ppmtv dimfactor [ppmfile] DESCRIPTION This program is part of Netpbm. ppmtv reads a PPM image as input and dims every other row of image data down by the specified dim factor. This factor may be in the range of 0.0 (the alternate lines are totally black) to 1.0 (original image). This creates an effect similar to what I've once seen in the video clip 'You could be mine' by Guns'n'Roses. In the scene I'm talking about you can see John Connor on his motorbike, looking up from the water trench (?) he's standing in. While the camera pulls back, the image gets 'normal' by brightening up the alternate rows of it. I thought this would be an interesting effect to try in MPEG. I did not yet check this out, however. Try for yourself. SEE ALSO ppm, ppmdim AUTHOR Copyright (C) 1993 by Frank Neumann Table Of Contents NAME SYNOPSIS DESCRIPTION SEE ALSO AUTHOR øpampop9 Updated: 02 March 2003 Table Of Contents NAME pampop9 - simulate a multi-lens camera such as the Pop9 SYNOPSIS pampop9 pnmfile|- xtiles ytiles xdelta ydelta DESCRIPTION This program is part of Netpbm. pampop9 tiles your starting image xtiles by ytiles times. Each of these tiles is taken from a slightly different offset within the source, as determined by the xdelta and ydelta arguments. The top line of tiles in the output is taken from the top of the source image, the second starts with the ydelta row of the source image, the next with the 2*ydelta row, and so on. Similarly, the first column of tiles in the output is taken from the left of the source image, the next starts with the xdelta column, the next with the 2*xdelta column, and so on. EXAMPLES With a 100 x 100 source image, then the output image from pampop9 3 3 10 10 will appear to be a three-by-three grid, each tile being 80 x 80 pixels. If the origin is taken to be the top-left corner, then the top row of tiles will take start at (0, 0) (10, 0) (20, 0) within the source image, the middle row will start at (0, 10) (10, 10) (20, 10), and the bottom row at (0, 20) (10, 20) (20, 20). HISTORY pampop9 was new in Netpbm 10.15 (April 2003). It was adapted slightly from pampup9, which was distributed by Robert Tinsley. At that time, it was distributed via http://www.thepoacher.net/code/#pampup9. By October 2004, that URL no longer was valid. SEE ALSO pnmtile AUTHOR Copyright (C) 2003 by Robert Tinsley. This software is released under the GPL ( http://www.fsf.org/licenses/gpl.txt). Table Of Contents NAME SYNOPSIS DESCRIPTION EXAMPLES SEE ALSO HISTORY AUTHOR