NAME¶
pstoimg - Convert a PostScript file to a bitmap image using Ghostscript and the
Netpbm utilities
SYNOPSIS¶
pstoimg -help |
-version
pstoimg [
-antialias ] [
-aaliastext ] [
-center num ]
[
-color num ] [
-crop code ] [
-debug ] [
-density num] [
-depth num ]
[
-discard ] [
-flip code ]
[
-geometry Xx
Y ] [
-interlaced ] [
-margins X,
Y ] [
-multipage ]
[
-out file ] [
-quiet ]
[
-rightjustify num ] [
-scale num ] [
-tmp path ] [
-topjustify [
x]
num ] [
-transparent ] [
-type type ]
[
-shoreup num[
d] ] [
-white ]
file [
file2 ... ]
OPTIONS¶
The command line options may be abbreviated to the shortest unique prefix.
- -help
- Show this help page and exit.
- -version
- Show the release and version of pstoimg and exit.
- -antialias
- Use Ghostscript's anti-aliasing feature for rendering
"softer" images. This applies to lines and edges of polygonal
and oval or circular shapes. Only valid if Ghostscript 4.03 or higher is
installed.
- -aaliastext
- Use Ghostscript's anti-aliasing feature for
"smoother" font characters, without the jagged edges. Similar to
-antialias for graphic components. Only valid if Ghostscript 4.03
or higher is installed.
- -center num
- Add the appropriate amount of whitespace to the left of the
image so that the image appears to be centered in a total width of
num pixels.
- -crop code
- Crop the bitmap from the given directions. code may
be a string of several cropping instructions, which are executed strictly
in the given order. Possible values are: h (horizontal, i.e. crop
top and bottom), v (vertical), tblr (top, bottom, left,
right) and a (all directions). A special case is s:
"shave" the image at the bottom, but only if a single line of
whitespace exists.
- -debug
- Turn on debugging output. This can get rather verbose. Any
intermediate files generated are not removed to help debugging.
- -density num
- The density (resolution) in DPI in which to render the
bitmap. The default is 72.
- -depth num or -color num
- Specify the color depth of the bitmap. Legal values are 1
(black & white), 8 (256 colors) and 24 (true color).
- -discard
- Delete the input postscript file if the conversion was
successful. Setting the environment DISCARD to a true value (as perl sees
it) has the same effect.
- -flip code
- Flip all generated output bitmaps. The following codes are
recognized: lr (flip left-right), tb (flip top-bottom), xy (flip
bottom/left-top/right), r90 and ccw (rotate by 90 degrees
counterclockwise), r270 and cw (rotate 90 degrees clockwise) and r180
(rotate 180 degrees).
- -geometry XxY
- Render only this "window" of the PostScript file.
If given, this option can dramatically reduce memory requirements and
speed up conversion. The geometry is automatically detected in case of EPS
files (Encapsulated PostScript).
- -interlaced
- Generate an interlaced bitmap. Interlaced images build up
from coarse to fine as they are loaded. This option may not work on every
installation and/or bitmap type, depending of the capabilities of external
programs.
- -margins X,Y
- The offset of the rectangle in the postscript file that is
going to be rendered from top/left. Can be used together with
-geometry to further reduce the size of the intermediate bitmap
file generated by Ghostscript.
- -multipage
- Process a multi-page PostScript file, i.e. create an
individual bitmap for every page. The resulting files are numbered: The
decimal number (starting with 1) is appended to the basename of the
PostScript input file (or the basename of the filename specified with
-out), while keeping the extension.
- -out file
- The file where to write the bitmap. If multiple PostScript
files are supplied on the command line, this option is ignored. The bitmap
type extension is appended automatically if file does not contain a
dot. In connection with -multipage file is extended by the
page number as shown in this example:
-outfile foo.gif --------> foo1.gif, foo2.gif, ...
- -quiet
- Do not print anything except error messages.
- -rightjustify num
- Add the appropriate amount of whitespace to the left of the
image so that it appears to be aligned to the right in a total width of
num pixels.
- -scale factor
- Scale the image by factor. Valid choices are any
numbers greater than zero. Useful choices are numbers between 0.1 - 5.
Large numbers may generate very large intermediate files and will take
longer to process. If this option is omitted, the environment SCALE is
considered.
- -shoreup num[d]
- Make height and width of the bitmap(s) an exact multiple of
num. If num is followed by a "d", then half the
extra vertical space is placed underneath. This option is useful, if you
want to have "blown-up" images of high quality for print, but
downscale them in HTML using "<IMG WIDTH=x HEIGHT=y>". If
the actual image is is not an integer multiple of x,y then browsers tend
to display distorted images.
- -tmp path
- Use path to store temporary files. Defaults to /tmp
on this installation. This parameter can be set by the environment
TMP or TEMP, too.
- -topjustify [x]num
- Add padding whitespace to the image so that it gets a
defined height. If an integer value is given, it defines the total height.
The whitespace is added at the bottom. If the number is preceded by
"x", then this multiple of the image height is added as
whitespace at the bottom.
- -transparent
- Generate transparent bitmaps, i.e. the background color
(white) is transparent if viewed with certain viewers (e.g. browsers).
This option may not be available due to missing capabilities of external
programs.
- -type type
- Instruct pstoimg to render the bitmap in type
format. Depending on the local installation, pstoimg is capable of
generating either GIF or PNG bitmaps. This site features the following
types: png gif
If omitted, the first type in this list is taken.
- -white
- Remove TeX's page color information from the PostScript
file before converting so that a white background is used.
DESCRIPTION¶
pstoimg iterates over the given input files and runs them through
Ghostscript. The resulting pnm (portable anymap files) are processed with
different Netpbm tools (cropping, color mapping, aligning, ...) and finally
converted into (currently) either GIF or PNG format. The bitmaps can now be
included e.g. in WWW pages.
The PostScript file is converted as is. If a valid bounding box is found (EPS
format), then only this area is converted. The image is
not cropped by
default.
RETURN VALUE¶
- 0
- if everything went all right
- x
- (x != 0) something went wrong. See the message output.
EXAMPLES¶
- "pstoimg foo.ps"
- Convert the first page of foo.ps to the default bitmap
type.
- "pstoimg -type png -crop a -trans -interlace
foo.ps"
- Same as above, but force png output and crop all the
whitespace around the image and make the color white transparent and
generate an interlaced bitmap.
- "pstoimg -multi -out bar -type gif -crop a
foo.ps"
- Consider foo.ps a multiple page PostScript file and create
output files bar1.gif, bar2.gif, etc.
ENVIRONMENT¶
- DENSITY, DEPTH, DEBUG, DISCARD
- See -density, -depth, -debug,
-discard, respectively.
- GS_LIB
- This variable is set to the path(s) where Ghostscript
libraries have been found on this system during configuration, but only if
the built-in paths are not correct. This fixes the problem of relocation
that is quite common on Win32 installations. This behavior can be
overridden by setting GS_LIB manually before starting pstoimg.
- LATEX2HTMLDIR
- The directory where the LaTeX2HTML library and perl modules
are found. Defaults to "/usr/share/latex2html" on this
installation.
- OUTFILE
- Setting this has the same effect as specifying -out.
Please do not rely on this feature any more, it will disappear from the
next releases!
- PAPERSIZE
- The papersize to use by Ghostscript to render the image.
pstoimg tries hard to optimize for rendering on the smallest possible
bitmap size. Still this option is there to enable tuning by hand, although
it is deprecated. If pstoimg finds a better setting, this parameter is
ignored.
- SCALE
- See the discussion of -scale.
- TMP and TEMP
- Unless overridden by -tmp, these variables denote a
directory where to store temporary files. TMP is considered first, then
TEMP.
SEE ALSO¶
gs, pnmcrop, pnmquant, pbmmake, pnmcat, pnmfile, pnmflip, ppmtogif, pnmtopng,
giftool, giftrans.
NOTES¶
Several people have suggested to use ImageMagick's convert instead of pstoimg. A
few comments on this: convert uses (of course) Ghostscript for conversion of
PostScript to bitmap, so one still needs gs. And for the special requirements
of LaTeX2HTML convert's features are not sufficient. The ImageMagick toolset
has everything in place, but it has some overhead that can prove killing when
processing some 100 images. pstoimg only does what it really has to, so it
should be quite efficient. Don't get me wrong - I like ImageMagick, but not in
the context of LaTeX2HTML.
CAVEATS¶
This utility is automatically configured and built to work on the local setup.
If this setup changes (e.g. some of the external commands are moved), the
script has be be reconfigured.
Despite the portability of perl, a pstoimg configured on UNIX will probably not
work on Win32 and vice versa.
BUGS¶
This is a major enhancement release, so there may be a few bugs. As the user
inteface changed a bit, some of your tools that were using pstoimg may not
work any more.
Please report bugs to latex2html@tug.org, stating the (debug) output of pstoimg,
your perl version and the versions of the external tools. Best is to include
the cfgcache.pm file from the configuration procedure.
AUTHOR¶
Marek Rouchal <marek@saftsack.fs.uni-bayreuth.de>
HISTORY¶
This script went through a long evolution, beginning with a modification of Doug
Crabill's <dgc@cs.purdue.edu> ps2epsi script. The first perl version was
done by Nikos Drakos <nikos@cbl.leeds.ac.uk>. It was gradually improved
by numerous LaTeX2HTML developers: Ross Moore <ross@maths.mq.edu.au>,
Jens Lippmann <lippmann@rbg.informatik.tu-darmstadt.de> and others
(sorry for not mentioning everyone and thanks for your contributions).