netpbm
User manual for Netpbm(0) User manual for Netpbm(0)
NAME
netpbm - netpbm library overview
Overview Of Netpbm
Netpbm is a package of graphics programs and a programming library.
There are over 220 separate programs in the package, most of which
have ’pbm’, ’pgm’, ’ppm’, ’pam’, or ’pnm’ in their names. For example,
pamscale(1)and giftopnm(1).
For example, you might use pamscale to shrink an image by 10%. Or use
pamcomp to overlay one image on top of another. Or use pbmtext to cre-
ate an image of text. Or reduce the number of colors in an image with
pnmquant.
Netpbm is an open source software package, distributed via the Source-
forge netpbm project .
The Netpbm Programs
The Netpbm programs are generally useful run by a person from a command
shell, but are also designed to be used by programs. A common charac-
teristic of Netpbm programs is that they are simple, fundamental build-
ing blocks. They are most powerful when stacked in pipelines. Netpbm
programs do not use graphical user interfaces (in fact, none of them
display graphics at all, except for a very simple Linux Svgalib dis-
player) and do not seek input from a user.
Each of these programs has its own manual, as linked in the directory
below.
The Netpbm programs can read and write files greater than 2 GiB wher-
ever the underlying system can. There may be exceptions where the pro-
grams use external libraries (The JPEG library, etc.) to access files
and the external library does not have large file capability. Before
Netpbm 10.15 (April 2003), no Netpbm program could read a file that
large.
Common Options
There are a few options that are present on all programs that are based
on the Netpbm library, including virtually all Netpbm programs. These
are not mentioned in the individual manuals for the programs.
You can use two hyphens instead of one on these options if you like.
-quiet Suppress all informational messages that would otherwise be
issued to Standard Error. (To be precise, this only works to
the extent that the program in question implements the Netpbm
convention of issuing all informational messages via the pm_mes-
sage() service of the Netpbm library).
-version
Instead of doing anything else, report the version of the lib-
netpbm library linked with the program (it may have been linked
statically into the program, or dynamically linked at run time).
Normally, the Netpbm programs and the library are installed at
the same time, so this tells you the version of the program and
all the other Netpbm files it uses as well.
-plain If the program generates an image in Netpbm format, generate it
in the "plain" (aka "ascii") version of the format, as opposed
to the "raw" (aka "binary") version.
This option was introduced in Netpbm 10.10 (October 2002).
Directory
Here is a complete list of all the Netpbm programs (with links to their
manuals):
Netpbmprogramdirectory(1)
How To Use The Programs
As a collection of primitive tools, the power of Netpbm is multiplied
by the power of all the other unix tools you can use with them. These
notes remind you of some of the more useful ways to do this. Often,
when people want to add high level functions to the Netpbm tools, they
have overlooked some existing tool that, in combination with Netpbm,
already does it.
Often, you need to apply some conversion or edit to a whole bunch of
files.
As a rule, Netpbm programs take one input file and produce one output
file, usually on Standard Output. This is for flexibility, since you
so often have to pipeline many tools together.
Here is an example of a shell command to convert all your of PNG files
(named *.png) to JPEG files named *.jpg:
for i in *.png; do pngtopnm $i | ppmtojpeg >‘basename $i .png‘.jpg; done
Or you might just generate a stream of individual shell commands, one
per file, with awk or perl. Here’s how to brighten 30 YUV images that
make up one second of a movie, keeping the images in the same files:
ls *.yuv
| perl -ne ’chomp;
print yuvtoppm $_ | ppmbrighten -v 100 | ppmtoyuv >tmp$$.yuv;
mv tmp$$.yuv $_
’
| sh
The tools find (with the -exec option) and xargs are also useful for
simple manipulation of groups of files.
Some shells’ ’process substitution’ facility can help where a non-
Netpbm program expects you to identify a disk file for input and you
want it to use the result of a Netpbm manipulation. Say the hypotheti-
cal program printcmyk takes the filename of a Tiff CMYK file as input
and what you have is a PNG file abc.png.
Try:
printcmyk <({ pngtopnm abc.png | pnmtotiffcmyk ; })
It works in the other direction too, if you have a program that makes
you name its output file and you want the output to go through a Netpbm
tool.
The Netpbm Formats
All of the programs work with a set of graphics formats called the
’netpbm’ formats. Specifically, these formats are pbm(1), pgm(1),
ppm(1), and pam(1).
The first three of these are sometimes known generically as ’pnm’.
Many of the Netpbm programs convert from a Netpbm format to another
format or vice versa. This is so you can use the Netpbm programs to
work on graphics of any format. It is also common to use a combination
of Netpbm programs to convert from one non-Netpbm format to another
non-Netpbm format. Netpbm has converters for about 100 graphics for-
mats, and as a package Netpbm lets you do more graphics format conver-
sions than any other computer graphics facility.
The Netpbm formats are all raster formats, i.e. they describe an image
as a matrix of rows and columns of pixels. In the PBM format, the pix-
els are black and white. In the PGM format, pixels are shades of gray.
In the PPM format, the pixels are in full color. The PAM format is
more sophisticated. A replacement for all three of the other formats,
it can represent matrices of general data including but not limited to
black and white, grayscale, and color images.
Programs designed to work with PBM images have ’pbm’ in their names.
Programs designed to work with PGM, PPM, and PAM images similarly have
’pgm’, ’ppm’, and ’pam’ in their names.
All Netpbm programs designed to read PGM images see PBM images as if
they were PGM too. All Netpbm programs designed to read PPM images see
PGM and PBM images as if they were PPM. See
Implied Format Conversion .
Programs that have ’pnm’ in their names read PBM, PGM, and PPM but
unlike ’ppm’ programs, they distinguish between them and their function
depends on the format. For example, pnmtopng(1)createsablackand-
whitePNG output image if its input is PBM or PGM, but a color PNG out-
put image if its input is PPM. And pnmrotate produces an output image
of the same format as the input. A hypothetical ppmrotate program
would also read all three PNM input formats, but would see them all as
PPM and would always generate PPM output.
Programs that have "pam" in their names read all the Netpbm formats:
PBM, PGM, PPM, and PAM. They sometimes treat them all as if they are
PAM, using an implied conversion, but often they recognize the individ-
ual formats and behave accordingly, like a "pnm" program does. See
Implied Format Conversion .
If it seems wasteful to you to have three separate PNM formats, be
aware that there is a historical reason for it. In the beginning,
there were only PBMs. PGMs came later, and then PPMs. Much later came
PAM, which realizes the possibility of having just one aggregate for-
mat.
The formats are described in the specifications of pbm(1), pgm(1),
ppm(1), and pam(1).
Implied Format Conversion
A program that uses the PGM library subroutines to read an image can
read a PBM image as well as a PGM image. The program sees the PBM
image as if it were the equivalent PGM image, with a maxval of 255.
note: This sometimes confuses people who are looking at the formats at
a lower layer than they ought to be because a zero value in a PBM
raster means white, while a zero value in a PGM raster means black.
A program that uses the PPM library subroutines to read an image can
read a PGM image as well as a PPM image and a PBM image as well as a
PGM image. The program sees the PBM or PGM image as if it were the
equivalent PPM image, with a maxval of 255 in the PBM case and the same
maxval as the PGM in the PGM case.
A program that uses the PAM library subroutines to read an image can
read a PBM, PGM, or PPM image as well as a PAM image. The program sees
a PBM image as if it were the equivalent PAM image with tuple type
BLACKANDWHITE. It sees a PGM image as if it were the equivalent PAM
image with tuple type GRAYSCALE. It sees a PPM image as if it were the
equivalent PAM image with tuple type RGB. But the program actually can
see deeper if it wants to. It can tell exactly which format the input
was and may respond accordingly. For example, a PAM program typically
produces output in the same format as its input.
Netpbm and Transparency
In many graphics formats, there’s a means of indicating that certain
parts of the image are wholly or partially transparent, meaning that if
it were displayed ’over’ another image, the other image would show
through there. Netpbm formats deliberately omit that capability, since
their purpose is to be extremely simple.
In Netpbm, you handle transparency via a transparency mask in a sepa-
rate (slightly redefined) PGM image. In this pseudo-PGM, what would
normally be a pixel’s intensity is instead an opaqueness value. See
pgm(1). pamcomp(1)isanexampleofaprogramthatuses a PGM transparency
mask.
Another means of representing transparency information has recently
developed in Netpbm, using PAM images. In spite of the argument given
above that Netpbm formats should be too simple to have transparency
information built in, it turns out to be extremely inconvenient to have
to carry the transparency information around separately. This is pri-
marily because Unix shells don’t provide easy ways to have networks of
pipelines. You get one input and one output from each program in a
pipeline. So you’d like to have both the color information and the
transparency information for an image in the same pipe at the same
time.
For that reason, some new (and recently renovated) Netpbm programs rec-
ognize and generate a PAM image with tuple type RGB_ALPHA or
GRAYSCALE_ALPHA, which contains a plane for the transparency informa-
tion. See thePAMspecification(1).
The Netpbm Library
The Netpbm programming library, libnetpbm(1),makesiteasytowriteprograms
that manipulate graphic images. Its main function is to read and write
files in the Netpbm formats, and because the Netpbm package contains
converters for all the popular graphics formats, if your program reads
and writes the Netpbm formats, you can use it with any formats.
But the library also contain some utility functions, such as character
drawing and RGB/YCrCb conversion.
The library has the conventional C linkage. Virtually all programs in
the Netpbm package are based on the Netpbm library.
netpbm-config
In a standard installation of Netpbm, there is a program named netpbm-
config in the regular program search path. We don’t consider this a
Netpbm program -- it’s just an ancillary part of a Netpbm installation.
This program tells you information about the Netpbm installation, and
is intended to be run by other programs that interface with Netpbm. In
fact, netpbm-config is really a configuration file, like those you typ-
ically see in the /etc/ directory of a Unix system.
Example:
$netpbm-config --datadir
/usr/local/netpbm/data
If you write a program that needs to access a Netpbm data file, it can
use such a shell command to find out where the Netpbm data files are.
netpbm-config is the only file that must be installed in a standard
directory (it must be in a directory that is in the default program
search path). You can use netpbm-config as a bootstrap to find all the
other Netpbm files.
There is no detailed documentation of netpbm-config. If you’re in a
position to use it, you should have no trouble reading the file itself
to figure out how to use it.
Other Graphics Software
Netpbm contains primitive building blocks. It certainly is not a com-
plete graphics software library.
Graphics Viewers
The first thing you will want to make use of any of these tools is a
viewer. (On GNU/Linux, you can use ppmsvgalib in a pinch, but it is
pretty limiting). zgv is a good full service viewer to use on a
GNU/Linux system with the SVGALIB graphics display driver library. You
can find zgv at ftp://ftp.ibiblio.org/pub/Linux/apps/graphics/view-
ers/svga .
zgv even has a feature in it wherein you can visually crop an image and
write an output file of the cropped image using pamcut(1).
See the -s option to zgv.
For the X inclined, there is also xzgv.
xloadimage and its extension xli are also common ways to display a
graphic image in X.
gqview is a more modern X-based image viewer.
qiv is a small, very fast viewer for X.
To play mpeg movies, such as produced by ppmtompeg, try xine .
See ftp://metalab.unc.edu/pub/Linux/apps/graphics/viewers/X .
Visual Graphics Software
Visual graphics software is modern point-and-click software that dis-
plays an image and lets you work on it and see the results as you go.
This is fundamentally different from what Netpbm programs do.
ImageMagick is like a visual version of Netpbm. Using the X/Window
system on Unix, you can do basic editing of images and lots of format
conversions. The package does include at least some non-visual tools.
convert, mogrify, montage, and animate are popular programs from the
ImageMagick package. ImageMagick runs on Unix, Windows, Windows NT,
Macintosh, and VMS.
xv is a very old and very popular simple image editor in the Unix
world. It does not have much in the way of current support, or mainte-
nance, though.
The Gimp is a visual image editor for Unix and X, in the same category
as the more famous, less capable, and much more expensive Adobe Photo-
shop, etc. for Windows. See http://www.gimp.org .
Electric Eyes, kuickshow, and gthumb are also visual editors for the
X/Window system, and KView and gwenview are specifically for KDE.
Programming Tools
If you’re writing a program in C to draw and manipulate images, check
out gd . Netpbm contains a C library for drawing images, but it is
probably not as capable or documented as gd. You can easily run any
Netpbm program from a C program with the pm_system function from the
Netpbm programming library, but that is less efficient than gd func-
tions that do the same thing.
Ilib is a C subroutine library with functions for adding text to an
image (as you might do at a higher level with pbmtext, pamcomp, etc.).
It works with Netpbm input and output. Find it at
http://www.radix.net/~cknudsen/Ilib . Netpbm also includes character
drawing functions in the libnetpbm(1)library,buttheydonothaveas fancy
font capabilities (see ppmlabel(1) for an example of use of the Netpbm
character drawing functions).
GD is a library of graphics routines that is part of PHP. It has a
subset of Netpbm’s functions and has been found to resize images more
slowly and with less quality.
Tools For Specific Graphics Formats
To create an animated GIF, or extract a frame from one, use gifsicle.
gifsicle converts between animated GIF and still GIF, and you can use
ppmtogif and giftopnm to connect up to all the Netpbm utilities. See
http://www.lcdf.org/gifsicle .
To convert an image of text to text (optical character recongition -
OCR), use gocr (think of it as an inverse of pbmtext). See http://alt-
mark.nat.uni-magdeburg.de/~jschulen/ocr/ .
http://schaik.com/pngsuite contains a PNG test suite -- a whole bunch
of PNG images exploiting the various features of the PNG format.
Another version of Netpbm’s pnmtopng/pngtopnm is at
http://www.schaik.com/png/pnmtopng.html(1).
The version in Netpbm was actually based on that package a long time
ago, and you can expect to find better exploitation of the PNG format,
especially recent enhancements, in that package. It may be a little
less consistent with the Netpbm project and less exploitive of recent
Netpbm format enhancements, though.
pngwriter is a C++ library for creating PNG images. With it, you plot
an image pixel by pixel. You can also render text with the FreeType2
library.
jpegtran Does some of the same transformations as Netpbm is famous for,
but does them specifically on JPEG files and does them without loss of
information. By contrast, if you were to use Netpbm, you would first
decompress the JPEG image to Netpbm format, then transform the image,
then compress it back to JPEG format. In that recompression, you lose
a little image information because JPEG is a lossy compression. Of
course, only a few kinds of lossless transformation are possible.
jpegtran comes with the Independent Jpeg Group’s ( http://www.ijg.org)
JPEG library.
Some tools to deal with EXIF files (see also Netpbm’s jpegtopnm(1)and
pnmtojpeg(1)):
To dump (interpret) an EXIF header: Exifdump (( http://topo.math.u-
psud.fr/~bousch/exifdump.py) ) or Jhead ( http://www.sentex.net/~mwan-
del/jhead. )
A Python EXIF library and dumper: http://pyexif.sourceforge.net.
Here’s some software to work with IOCA (Image Object Content Architec-
ture): ImageToolbox ($2500, demo available). This can convert from
TIFF -> IOCA and back again. Ameri-Imager(1) ($40 Windows only).
pnm2ppa converts to HP’s ’Winprinter’ format (for HP 710, 720, 820,
1000, etc). It is a superset of Netpbm’s pbmtoppa and handles,
notably, color. However, it is more of a printer driver than a Netpbm-
style primitive graphics building block. See http://source-
forge.net/project/?group_id=1322 .
Document/Graphics Software
There is a large class of software that does document processing, and
that is somewhat related to graphics because documents contain graphics
and a page of a document is for many purposes a graphic image. Because
of this slight intersection with graphics, I cover document processing
software here briefly, but it is for the most part beyond the scope of
this document.
First, we look at where Netpbm meets document processing. pstopnm con-
verts from Postscript and PDF to PNM. It effectively renders the docu-
ment into images of printed pages. pstopnm is nothing but a convenient
wrapper for Ghostscript , and in particular Netpbm-format device
drivers that are part of it. pnmtops and pbmtoepsi convert a PNM image
to a Postscript program for printing the image. But to really use PDF
and Postscript files, you generally need more complex document process-
ing software.
Adobe invented Postscript and PDF and products from Adobe are for many
purposes the quintessential Postscript and PDF tools.
Adobe’s free Acrobat Reader displays PDF and converts to Postscript.
The Acrobat Reader for unix has a program name of ’acroread’ and the
-toPostScript option (also see the -level2 option) is useful.
Other software from Adobe, available for purchase, interprets and cre-
ates Postscript and PDF files. ’Distill’ is a program that converts
Postscript to PDF.
xpdf also reads PDF files.
GSview, ghostview, gv, ggv, and kghostview are some other viewers for
Postscript and PDF files.
The program ps2pdf, part of Ghostscript, converts from Postscript to
PDF.
Two packages that produce more kinds of Encapsulated Postscript than
the Netpbm programs, including compressed kinds, are bmeps and imgtops
.
dvips converts from DVI format to Postscript. DVI is the format that
Tex produces. Netpbm can convert from Postscript to PNM. Thus, you
can use these in combination to work with Tex/Latex documents graphi-
cally.
wvware converts a Microsoft Word document (.doc file) to various other
formats. While the web page doesn’t seem to mention it, it reportedly
can extract an embedded image in a Word document as a PNG.
Latex2html converts Latex document source to HTML document source.
Part of that involves graphics, and Latex2html uses Netpbm tools for
some of that. But Latex2html through its history has had some rather
esoteric codependencies with Netpbm. Older Latex2html doesn’t work
with current Netpbm. Latex2html-99.2beta8 works, though.
Other
The file program looks at a file and tells you what kind of file it is.
It recognizes most of the graphics formats with which Netpbm deals, so
it is pretty handy for graphics work. Netpbm’s anytopnm(1)programde-
pendsonfile. See ftp://ftp.astron.com/pub/file .
The Utah Raster Toolkit serves a lot of the same purpose as Netpbm, but
without the emphasis on format conversions. This package is based on
the RLE format, which you can convert to and from the Netpbm formats.
http://www.cs.utah.edu/gdc/projects/urt.html(1) gives some information
on the Utah Raster Toolkit, but does not tell where to get it.
Ivtools is a suite of free X Windows drawing editors for Postscript,
Tex, and web graphics production, as well as an embeddable and extend-
able vector graphic shell. It uses the Netpbm facilities. See
http://www.ivtools.org .
The program morph morphs one image into another. It uses Targa format
images, but you can use tgatoppm and ppmtotga to deal with that format.
You have to use the graphical (X/Tk) Xmorph to create the mesh files
that you must feed to morph. morph is part of the Xmorph package. See
http://www.colorado-research.com/~gourlay/software/Graphics/Xmorph .
Other Graphics Formats
People never seem to tire of inventing new graphics formats, often com-
pletely redundant with pre-existing ones. Netpbm cannot keep up with
them. Here is a list of a few that we know Netpbm does not handle
(yet).
Various commercial Windows software handles dozens of formats that
Netpbm does not, especially formats typically used with Windows pro-
grams. ImageMagick is probably the most used free image format con-
verter and it also handles lots of formats Netpbm does not.
· VRML (Virtual Reality Modelling Language)
· CAL (originated by US Department Of Defense, favored by archi-
tects). http://www.landfield.com/faqs/graphics/fileformats-
faq/part3/section-24.html(1)
· array formats dx, general, netcdf, CDF, hdf, cm
· CGM+
· Windows Meta File (.WMF). Libwmf converts from WMF to things
like Latex, PDF, PNG. Some of these can be input to Netpbm.
· Microsoft Word, RTF. Microsoft keeps a proprietary hold on
these formats. Any software you see that can handle them is
likely to cost money.
· DXF (AutoCAD)
· IOCA (Image Object Content Architecture) The specification of
this format is documented by IBM:
Data Stream and Object Architectures: Image Object Content
Architecture Reference . See above for software that processes
this format.
· SVG. Find out about this vector graphics format and software to
use with it at this Worldwide Web Consortium web page .
· OpenEXR is an HDR format (like PFM(1)). See
http://www.openexr.org/about.html (1).
· Xv Visual Schnauzer thumbnail image. This is a rather anti-
quated format used by the Xv program. In Netpbm circles, it is
best known for the fact that it is very similar to Netpbm for-
mats and uses the same signature (’P7’) as PAM because it was
developed as sort of a fork of the Netpbm format specifications.
· YUV 4:2:0, aka YUV 420, and the simlar YUV 4:4:4, YUV 4:2:2, YUV
4:1:1, YUV 4:1:1s, and YUV 4:1:0. Video systems often use this.
History
Netpbm has a long history, starting with Jef Poskanzer’s Pbmplus pack-
age in 1988. The file HISTORY in the Netpbm source code contains a
historical overview as well as a detailed history release by release.
Author
Netpbm is based on the Pbmplus package by Jef Poskanzer, first dis-
tributed in 1988 and maintained by him until 1991. But the package
contains work by countless other authors, added since Jef’s original
work. In fact, the name is derived from the fact that the work was
contributed by people all over the world via the Internet, when such
collaboration was still novel enough to merit naming the package after
it.
Bryan Henderson has been maintaining Netpbm since 1999. In addition to
packaging work by others, Bryan has also written a significant amount
of new material for the package.
netpbm documentation 15 April 2005 User manual for Netpbm(0)
Man(1) output converted with
man2html