Pnmtops User Manual(1) General Commands Manual Pnmtops User Manual(1)
NAME
pnmtops - convert PNM image to Postscript
SYNOPSIS
pnmtops [-scale=s] [-dpi=N[xN]] [-imagewidth=n] [-imageheight=n]
[-width=N] [-height=N] [-equalpixels] [-bitspersample=N] [-turn|-noturn]
[-rle|-runlength] [-flate] [-ascii85] [-nocenter|-center] [-noset-
page|-setpage] [-level=N] [-dict] [-vmreclaim] [-psfilter] [-noshowpage]
[-verbose] [pnmfile]
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(1).
pnmtops reads a Netpbm image stream as input and produces Encapsulated
Postscript (EPSF) as output.
(Note: people usually render the name as "PostScript," but we use stan-
dard typography in the Netpbm manual, so capitalize only the first let-
ter).
If the input file is in color (PPM), pnmtops generates a color Post-
script file. Some Postscript interpreters can't handle color Post-
script. If you have one of these you will need to run your image
through ppmtopgm first.
If you specify no output dimensioning options, the output image is di-
mensioned as if you had specified -scale=1.0, which means approximately
72 pixels of the input image generate one inch of output (if that fits
the page).
Use -imagewidth, -imageheight, -equalpixels, -width, -height, and -scale
to adjust that.
Each image in the input stream becomes one complete one-page Postscript
program in the output. (This may not be the best way to create a multi-
page Postscript stream; someone who knows Postscript should work on
this).
The line at the top of the file produced by pnmtops is either "%!PS-
Adobe-3.0 EPSF-3.0" or just "%!PS-Adobe-3.0". The numbers do not re-
flect the Postscript language level, but the version of the DSC comment
specification and EPS specification implemented. The Postscript lan-
guage level is in the "%%LanguageLevel:" comment. pnmtops omits
"EPSF-3.0" if you specify -setpage, because it is incorrect to claim EPS
compliance if the file uses setpagedevice.
What is Encapsulated Postscript?
Encapsulated Postscript (EPSF) is a subset of Postscript (i.e. the set
of streams that conform to EPSF is a subset of those that conform to
Postscript). It is designed so that an EPSF stream can be embedded in
another Postscript stream. A typical reason to do that is to have an
EPSF stream that describes a picture you can put in a larger document.
But EPSF is not an image format -- converting from Netpbm format to EPSF
really means generating a program to print that Netpbm image on paper.
Note that there are myriad ways to print an image on paper; pnmtops com-
mand line options let you control some of them.
An Encapsulated Postscript document conforms to the DSC (Document Struc-
turing Convention). The DSC defines some Postscript comments (they're
comments from a Postscript point of view, but have semantic value from a
DSC point of view).
More information about Encapsulated Postscript is at http://www.tailre-
cursive.org/postscript/eps.html" (1).
Many of the ideas in pnmtops come from Dirk Krause's bmeps. See ]8;;#seealso\SEE
ALSO]8;;\ .
OPTIONS
In addition to the options common to all programs based on libnetpbm
(most notably -quiet, see ]8;;index.html#commonoptions\ Common Options]8;;\ ), pnmtops recognizes the fol-
lowing command line options:
-imagewidth, -imageheight
Tells how wide and high you want the image on the page, in
inches. The aspect ratio of the image is preserved, so if you
specify both of these, the image on the page will be the largest
image that will fit within the box of those dimensions.
If these dimensions are greater than the page size, you get Post-
script output that runs off the page.
You cannot use imagewidth or imageheight with -scale or
-equalpixels.
-equalpixels
This option causes the output image to have the same number of
pixels as the input image. So if the output device is 600 dpi
and your image is 3000 pixels wide, the output image would be 5
inches wide.
You cannot use -equalpixels with -imagewidth, -imageheight, or
-scale.
-bitspersample=N
This option selects the number of bits for each component of each
pixel in the Postscript output. By default, pnmtops chooses the
value that corresponds to the maxval of the PNM input, subject to
constraints of the Postscript language. In particular, if you
don't select Postscript level 2 (-level) with built-in Postscript
(-psfilter), the most bits per pixel you can have is 8.
The value must be 1, 2, 4, 8, or 12, with 12 being restricted to
the case described above.
This option was new in Netpbm 10.51 (June 2010).
-scale tells how big you want the image on the page. The value is the
number of inches of output image that you want 72 pixels of the
input to generate.
But pnmtops rounds the number to something that is an integral
number of output device pixels. E.g. if the output device is 300
dpi and you specify -scale=1.0, then 75 (not 72) pixels of input
becomes one inch of output (4 output pixels for each input
pixel). Note that the -dpi option tells pnmtops how many pixels
per inch the output device generates.
If the size so specified does not fit on the page (as measured
either by the -width and -height options or the default page size
of 8.5 inches by 11 inches), pnmtops ignores the -scale option,
issues a warning, and scales the image to fit on the page.
-dpi=N[xN]
This option specifies the dots per inch resolution of your output
device. The default is 300 dpi. In theory PostScript is device-
independent and you don't have to worry about this, but in prac-
tice its raster rendering can have unsightly bands if the device
pixels and the image pixels aren't in sync.
Also this option is crucial to the working of the equalpixels op-
tion.
If you specify NxN, the first number is the horizontal resolution
and the second number is the vertical resolution. If you specify
just a single number N, that is the resolution in both direc-
tions.
-width, -height
These options specify the dimensions, in inches, of the page on
which the output is to be printed. This can affect the size of
the output image.
The page size has no effect, however, when you specify the -im-
agewidth, -imageheight, or -equalpixels options.
These options may also affect positioning of the image on the
page and even the paper selected (or cut) by the printer/plotter
when the output is printed. See the -nosetpage option.
The default is 8.5 inches by 11 inches.
-turn
-noturn
These options control whether the image gets turned 90 degrees.
Normally, if an image fits the page better when turned (e.g. the
image is wider than it is tall, but the page is taller than it is
wide), it gets turned automatically to better fit the page. If
you specify the -turn option, pnmtops turns the image no matter
what its shape; If you specify -noturn, pnmtops does not turn it
no matter what its shape.
-rle
-runlength
These identical options tell pnmtops to use run length compres-
sion in encoding the image in the Postscript program. This may
save time if the host-to-printer link is slow; but normally the
printer's processing time dominates, so -rle has no effect (and
in the absence of buffering, may make things slower).
This may, however, make the Postscript program considerable
smaller.
This usually doesn't help at all with a color image and -psfil-
ter, because in that case, the Postscript program pnmtops creates
has the red, green, and blue values for each pixel together,
which means you would see long runs of identical bytes only in
the unlikely event that the red, green, and blue values for a
bunch of adjacent pixels are all the same. But without -psfil-
ter, the Postscript program has all the red values, then all the
green values, then all the blue values, so long runs appear wher-
ever there are long stretches of the same color.
Here is an explanation by Jef Poskanzer of why he invented the
-rle option:
I just spent a few hours modifying my pbmtops filter to produce
run length encoded PostScript output. The results are not spec-
tacular for me - yes, the files are smaller, but the printing
times are about the same. But I'm printing over the network. If
you were stuck with the serial line, this would be a big win.
I've appended a sample program generated by my filter. If anyone
sees ways to improve the code, please let me know, I'm not much
of a PostScript hacker. This version of pbmtops will be distrib-
uted to comp.sources.misc and expo.lcs.mit.edu sometime in Octo-
ber. - Jef
This is from a forum about Postscript (http://www.lngpstscrpt.tk/re-
postscript-run-length-encoding-again), extracted in October 2010. Jef
added -rle in August 1988. In those days, RS-232 lines (referred to as
"serial" in the quotation) were typically 9600bps. 2400 bps lines were
still around. What the quotation calls "the network" is probably a 10
Mbps Ethernet connection.
-flate This option tells pnmtops to use "flate" compression (i.e. com-
pression via the "Z" library -- the same as PNG).
See the -rle option for information about compression in general.
You must specify -psfilter if you specify -flate.
There exist modern versions of pnmtops that cannot do flate com-
pression; these versions were built without the Z library and
built not to require the Z library. If you have such a version,
it fails with an explanatory error message when you specify
-flate.
This option was new in Netbpm 10.27 (March 2005).
Before Netpbm 10.32 (February 2006), you could not specify -rle
and -flate together.
-ascii85
By default, pnmtops uses "asciihex" encoding of the image raster.
The image raster is a stream of bits, while a Postscript program
is text, so there has to be an encoding from bits to text. Asci-
ihex encoding is just the common hexadecimal representation of
bits. E.g. 8 1 bits would be encoded as the two characters "FF".
With the -ascii85 option, pnmtops uses "ascii85" encoding in-
stead. This is an encoding in which 32 bits are encoded into
five characters of text. Thus, it produces less text for the
same raster than asciihex. But ascii85 is not available in Post-
script Level 1, whereas asciihex is.
This option was new in Netbpm 10.27 (March 2005).
-psfilter
pnmtops can generate two different kinds of Encapsulated Post-
script programs to represent an image. By default, it generates
a program that redefines readstring in a custom manner and
doesn't rely on any built-in Postscript filters. But with the
-psfilter option, pnmtops leaves readstring alone and uses the
built-in Postscript filters /ASCII85Decode, /ASCIIHexDecode,
/RunLengthDecode, and /FlateDecode.
This option was new in Netbpm 10.27 (March 2005). Before that,
pnmtops always used the custom readstring.
The custom code can't do flate or ascii85 encoding, so you must
use -psfilter if you want those (see -flate, -ascii85).
-level This option determines the level (version number) of Postscript
that pnmtops uses. By default, pnmtops uses Level 2. Some fea-
tures of pnmtops are available only in higher Postscript levels,
so if you specify too low a level for your image and your op-
tions, pnmtops fails. For example, pnmtops cannot do a color im-
age in Level 1.
This option was new in Netpbm 10.27 (March 2005). Before that,
pnmtops always used Level 2.
-dict This causes the Postscript program create a separated dictionary
for its local variables and remove it from the stack as it exits.
This option was new in Netbpm 10.27 (March 2005).
-vmreclaim
This option causes the Postscript program to force a memory
garbage collection as it exits.
This option was new in Netbpm 10.27 (March 2005).
-nocenter
By default, pnmtops centers the image on the output page.
You can cause pnmtops to instead put the image against the
lower left corner of the page with the -nocenter
option. This is useful for programs which can include
PostScript files, but can't cope with pictures which are not
positioned in the lower left corner.
If you want to position an image on the page arbitrarily,
use
pamcomp to create an image of the full page with the image
in
question at the proper place and the rest of the page white,
and use
pnmtops to convert the composed result to Encapsulated Post-
script.
For backward compatibility, pnmtops accepts the option
-center, but it has no effect.
-setpage
This causes pnmtops to include a "setpagedevice"
directive in the output. This causes the output to violate
specifications
of EPSF encapsulated Postscript, but if you're not using it
in an
encapsulated way, may be what you need. The directive tells
the
printer/plotter what size paper to use (or cut). The dimen-
sions it
specifies on this directive are those selected by the
-width and -height options or defaulted.
From January through May 2002, the default was to include
"setpagedevice" and this option did not exist. Before
January 2002, there was no way to include "setpagedevice"
and neither the -setpage nor -nosetpage option existed.
-nosetpage
This tells pnmtops not to include a "setpagedevice"
directive in the output. This is the default, so the option
has no
effect.
See the -setpage option for the history of this option.
-noshowpage
This tells pnmtops not to include a "showpage"
directive in the output. By default, pnmtops includes a
"showpage" at the end of the EPSF program. According to
EPSF specs, this is OK, and the program that includes the
EPSF is
supposed to redefine showpage so this doesn't cause undesir-
able
behavior. But it's often easier just not to have the show-
page.
This options was new in Netpbm 10.27 (March 2005). Earlier
versions of pnmtops always include the showpage.
-showpage
This tells pnmtops to include a "showpage" directive
at the end of the EPSF output. This is the default, so the
option has
no effect.
This option was new in Netpbm 10.27 (March 2005).
-verbose
This causes informational messages about the conversion
process and
result.
LIMITATIONS
If the PNM image has a maxval greater than 255, pnmtops will produce
output with 8 bits per sample resolution unless you specify -psfilter,
even though Postscript Level 2 has a 12 bits per sample format. pnm-
tops's custom raster-generating code just doesn't know the 12 bit for-
mat.
APPLICATIONS
You can use the Postscript output a number of ways. Many printers take
Postscript input (but you still need some kind of printer driver to
transport the Postscript to the printer).
There is also the Ghostscript program (not part of Netpbm), which takes
Postscript as input and generates an output stream to control any of
myriad models of printer (but you still need some kind of printer driver
to transport that stream to the printer).
Ghostscript also can convert the Postscript file to PDF, which is a very
popular document and image format. Use Ghostscript's pdfwrite output
device type. The program ps2pdf (distributed with Ghostscript) is a
convenient way to run Ghostscript with pdfwrite. For more information
about converting to and from PDF, see ]8;;index.html#document\Document/Graphics Software]8;;\ .
SEE ALSO
bmpp(1) converts from Netpbm and other formats to Encapsulated Post-
script.
bmpp has a few functions pnmtops does not, such as the ability to use
LZW compression.
pnm(1), gs, psidtopgm(1), pstopnm(1), pbmtolps(1), pbmtoepsi(1), pbm-
topsg3(1), ppmtopgm(1),
HISTORY
Copyright (C) 1989, 1991 by Jef Poskanzer.
Modified November 1993 by Wolfgang Stuerzlinger, wrzl@gup.uni-linz.ac.at
The program was originally pbmtops. It became pgmtops in October 1988
and was merged with ppmtops to form pnmtops in January 1991. ppmtops
came into being some time before September 1989.
Table Of Contents
• ]8;;#synopsis\SYNOPSIS]8;;\
• ]8;;#description\DESCRIPTION]8;;\
• ]8;;#options\OPTIONS]8;;\
• ]8;;#limitations\LIMITATIONS]8;;\
• ]8;;#applications\APPLICATIONS]8;;\
• ]8;;#seealso\SEE ALSO]8;;\
• ]8;;#history\HISTORY]8;;\
DOCUMENT SOURCE
This manual page was generated by the Netpbm tool 'makeman' from HTML
source. The master documentation is at
http://netpbm.sourceforge.net/doc/pnmtops.html
netpbm documentation 21 February 2024 Pnmtops User Manual(1)
Generated by dwww version 1.16 on Tue Dec 16 04:43:57 CET 2025.