FAQ |
PDF manual "bmeps.pdf" available |
Basics
What is bmeps?
bmeps is a project to add bitmap graphics support to dvips.
It consists of three parts:
- a library containing routines for conversion from different bitmap graphic types to EPS,
- a command line tool to do conversions and to get bounding box data and
- modifications in dvips sources to call these routines.
Which filetypes are supported?
The filetypes supported are:
- PNG
- JPEG
- PNM/PPM/PGM/PBM
- it provides a good compression rata,
- the compression is not lossy and
- the license conditions allow to distribute PNG related software as open source.
The JPEG file format uses DCT compression. Compression is lossy, typically the picture quality can be adjusted by the user during JPEG export in graphics applications.
The JPEG file format is a good choice for "natural scenes" such as photos.
DCT decompression output is not a good candidate for run-length or flate compression as used in bmeps so bmeps is not the best choice for JPEG to EPS conversion.
To convert JPEG images to EPS you should use imgtops2 or jpeg2ps.
Support for NetPBM filetypes was added because it allows to use a lot of image file types via the NetPBM tools.
One can convert other image types to EPS by
xxxtopnm image.xxx | bmeps > image.epsThe library can be extended to add support for further filetypes.
Installation
Where can I get it?
Source code and documentation can be found at
http://sourceforge.net/projects/bmeps.
What other software is required to install bmeps?
You need to install
- zlib, http://www.gzip.org/zlib/ and
- libpng, http://www.libpng.org/pub/png/libpng.html
- JPEG lib, ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6b.tar.gz (optional)
- NetPBM, ftp://ftp.metalab.unc.edu/pub/Linux/apps/graphics/convert/netpbm-10.11.10.tgz (optional)
Install the libraries in the given order, set the environment variables CPPFLAGS, CFLAGS and LDFLAGS so the header files and libraries are found.
Example:
CPPFLAGS: -I/usr/local/netpbm/include -I/usr/local/include -I/usr/include CFLAGS: -KPIC -xCC -v -I/usr/local/netpbm/include -I/usr/local/include -I/usr/include LDFLAGS: -L/usr/local/netpbm/lib -L/usr/local/lib -L/usr/lib
How do I install the bmeps library?
Unpack the bmeps.tgz file.
Change into the bmeps directory, run
./configure make make installMake sure to set the environment variable CFLAGS and LDFLAGS properly.
Should I build a modified dvips driver?
This depends on your situation.
The modified driver runs faster when converting pictures because
it is not necessary to start background processes for each picture.
How do I build the modified dvips driver?
Unpack kpathsea-*.tar.gz and dvipsk-*.tar.gz
from within the same directory.
Make sure the environment variables needed to run TeX are set.
Change into the kpathsea-* directory and run
./configure ... make make installNow go into the dvipsk-* directory and run
./configure ... make make installPossibly you want to make a backup copy of the unmodified dvips as dvips.original.
If you succeeded to build an unmodified dvips you can copy the contents of the .../bmeps/dvips-mods directory into the dvipsk source directory.
Now run
./configure ... make make installagain to build and install the modified dvips.
I'm on a Win32 system. Is there a binary?
Binaries are placed in the WIN32BIN subdirectory.
Copy the *.exe and *.dll files into a directory mentioned in the
PATH environment variable.
Make sure not to overwrite or hide existing DLLs.
I'm on a Win32 system. How can I build bmeps.exe?
Building bmeps.exe is not trivial and requires practical
skills in using your development software on Win32.
For normal users I recommend to use the binary package mentioned above.
The text below gives a general guideline how to build the executable
and the libraries it depends on. Depending on library versions and depending
on your development software the information below might be only
partially valid.
First we need to create the zlib library.
Create a new project of type "Win32 static library".
Add the sources
- adler32.c
- compress.c
- crc32.c
- deflate.c
- gzio.c
- infblock.c
- infcodes.c
- inffast.c
- inflate.c
- inftrees.c
- infutil.c
- trees.c
- uncompr.c
- zutil.c
Now we can create the libpng library.
Create a new project of type "Win32 static library".
Add the sources
- png.c
- pngerror.c
- pngget.c
- pngmem.c
- pngpread.c
- pngread.c
- pngrio.c
- pngrtran.c
- pngrutil.c
- pngset.c
- pngtrans.c
- pngwio.c
- pngwrite.c
- pngwtran.c
- pngwutil.c
If you want JPEG support we need to create the JPEG library. Create a new project of type "Win32 static library".
Add the sources
- jcomapi.c
- jdapimin.c
- jdapistd.c
- jdatasrc.c
- jdcoefct.c
- jdcolor.c
- jddctmgr.c
- jdhuff.c
- jdinput.c
- jdmainct.c
- jdmarker.c
- jdmaster.c
- jdmerge.c
- jdphuff.c
- jdpostct.c
- jdsample.c
- jerror.c
- jfdctflt.c
- jfdctfst.c
- jidctflt.c
- jidctfst.c
- jidctint.c
- jidctred.c
- jmemmgr.c
- jmemnobs.c
- jquant1.c
- jquant2.c
- jutils.c
Create a file jconfig.h with contents as follows:
#define HAVE_PROTOTYPES #define HAVE_UNSIGNED_CHAR #define HAVE_UNSIGNED_SHORT #undef void #undef const #undef CHAR_IS_UNSIGNED #define HAVE_STDDEF_H #define HAVE_STDLIB_H #undef NEED_BSD_STRINGS #undef NEED_SYS_TYPES_H #undef NEED_FAR_POINTERS #undef NEED_SHORT_EXTERNAL_NAMES /* Define this if you get warnings about undefined structures. */ #undef INCOMPLETE_TYPES_BROKEN #ifdef JPEG_INTERNALS #undef RIGHT_SHIFT_IS_UNSIGNED #define INLINE /* These are for configuring the JPEG memory manager. */ #undef DEFAULT_MAX_MEM #undef NO_MKTEMP #endif /* JPEG_INTERNALS */ #ifdef JPEG_CJPEG_DJPEG #define BMP_SUPPORTED /* BMP image file format */ #define GIF_SUPPORTED /* GIF image file format */ #define PPM_SUPPORTED /* PBMPLUS PPM/PGM image file format */ #undef RLE_SUPPORTED /* Utah RLE image file format */ #define TARGA_SUPPORTED /* Targa image file format */ #undef TWO_FILE_COMMANDLINE #undef NEED_SIGNAL_CATCHER #undef DONT_USE_B_MODE /* Define this if you want percent-done progress reports from cjpeg/djpeg. */ #undef PROGRESS_REPORT #endif /* JPEG_CJPEG_DJPEG */and build the library.
If you want NetPBM support we need to create a pbm library. Create a new project of type "Win32 static library".
Add the sources
- libpbm1.c
- libpbm2.c
- libpbm3.c
- libpbm4.c
- libpbm5.c
- libpgm1.c
- libpgm2.c
- libpnm1.c
- libpnm2.c
- libpnm3.c
- libpnm4.c
- libppm1.c
- libppm2.c
- libppm3.c
- libppm4.c
- libppm5.c
- shhopt.c from the shhopt subdirectory.
Add the following code to shhopt.c:
char *rindex(char *s, int c) { char *back = NULL; char *ptr; ptr = s; while(*ptr) { if(*ptr == c) { back = ptr; } ptr++; } return back; }and build the library.
If there are error messages about an include file "unistd.h" not found, remove all occurances of
#include <unistd.h>or
#include "unistd.h"
Now create a new project of type "Win32 Console Application" named bmeps.
Add the sources
- bmepsm.c
- bmeps.c
- bmepsoe.c
- pngeps.c
- jpgeps.c
- pnmeps.c
- tifeps.c
Add the libraries created above to the project.
Now we need to edit the file bmepsco.h. By default all the libraries are enabled by HAVE_... contants. To disable libraries define the appropriate constants to 0:
JPEG | HAVE_JPEGLIB_H |
NetPBM | HAVE_PNM_H |
Where can I get a Win32 binary of the modified dvips?
The MikTeX 2.1 distribution includes a dvips
containing the bitmap support.
See http://www.miktex.org.
Usage
What must I do in my LaTeX source to use bitmap graphics?
If you use the modified dvips add
\DeclareGraphicsRule{.png}{eps}{.bb}{}to your LaTeX source's preamble.
If you use an unmodified dvips add
\DeclareGraphicsRule{.png}{eps}{.bb}{`bmeps <bmeps-options> #1}instead. See below for bmeps options.
To include a graphics file, type
\includegraphics{file.png}You can also specifiy additional options like
\includegraphics[width=\linewidth]{file.png}
What's the .bb file for?
To calcaluate the documents layout LaTeX needs information
about the bounding boxes of included graphics.
In EPS files this information is contained in a line like
%%BoundingBox: 0 0 800 600directly in the file.
Other file types do not allow text lines in the file, a separated file must contain this information.
How can I build the .bb file?
Use
bmeps -b file.png file.bbto create the bounding box file file.bb for file.png.
Can I use PNGs with both latex/dvips and pdflatex?
Of course you can.
In your documents preamble (before \begin{document}) write
\usepackage{ifpdf} \ifpdf ... \else \DeclareGraphicsRule{.png}{eps}{.bb}{} \fifor modified dvips or
\usepackage{ifpdf} \ifpdf ... \else \DeclareGraphicsRule{.png}{eps}{.bb}{`bmeps #1} \fifor unmodified dvips.
If your document contains EPS graphics too, you should change
\includegraphics[...]{xxx.eps}to
\includegraphics[...]{xxx}and provide both an EPS and a PDF version of the picture.
Use
ps2pdf xxx.eps xxx.pdfor - for large pictures -
cat xxx.eps | epsffit -c 87 92 487 363 | ps2pdf - xxx.pdfto convert the EPS file to PDF.
The epsffit program is contained in the psutils (http://www.dcs.ed.ac.uk/home/ajcd/psutils/index.html).
The ps2pdf script is contained in the Gostscript distributions. (http://www.cs.wisc.edu/~ghost)
Which options are recognized by bmeps?
bmeps can be used to do bitmap-to-EPS conversions from commandline.
The syntax is
bmeps [ <options> ] [ <inputfile> [ <outputfile> ] ]The following options can be used:
- -p #
specifies the PS level. Use -p 1 to select PS level 1, -p 2 for PS level 2 and -p 3 for level 3. - -c
turns color printing on. This options requires PS level 2 or higher. - -g
turns color printing off. Use either -c or -g. - -e<encoding>
Selects encoding mechanisms.
Specifiy r to turn run-length-encoding on, 8 to turn ASCII-85-encoding on and f to turn flate encoding on. - -d
turns draft mode on. No image is printed, a placeholder is printed instead. - -b
prints bounding-box-information only. - -a<alpha-channel-options>
When using PS level 3 you can use images containing masks. A PNG alpha channel can be converted into a mask. Specify either o if the alpha channel expresses opacity (default) or t if it specifies transparency.
In standard mode all pixels having at least some opacity are drawn, only opacity 0 is masked. If you specify flag l you use an alternative behaviour, only full opacity pixels are drawn, all others are masked.
Option m advises the program to mix foreground and background color for a pixel depending on its alpha value.
You can specify a background color like 128,255,128 for light green. Normally this background color is used only if there is no background color chunk in the file. Option s gives this command line background color higher priority than the background color from chunk.
Alpha channel support is available only if the bmeps library was configured for alpha channel support.
- bmeps -p1
creates output for a PS level 1 printer - bmeps -p2 -g -er8
creates output for a PS level 2 grayscale printer. - bmeps -p2 -c -er8
creates output for a PS level 2 color printer. - bmeps -p3 pc -er8f
creates output for a PS level 3 application. - bmeps -d
creates a draft only. - bmeps -b
prints bounding-box-information.
How can I use bitmap graphics with the modified dvips?
Options for bitmap-to-EPS-conversion can be specified on the command
line. Use
dvips -I <conversion-options> ...where <conversion-options> is a string containing of the following:
- PS level
Specify 1, 2 or 3 to select the PS level your printer supports. - Color / Grayscale printing
Specifiy c for color printing or g for grayscale printing. Color printing is available for PS level 2 and higher. - Encoding
PS level 2 enables run-length-encoding and ASCII85-encoding. PS level 3 enables flate encoding. The different encodings may be combined.
Specify r for run-length-encoding, 8 for ASCII-85-encoding and f for flate encoding.
- Draft mode
In draft mode the picture is not converted and inserted into the PS output, a placeholder is printed instead.
Type the character d to turn draft mode on.
If this character is omitted draft mode is turned off. - Alpha channel use
To convert an alpha channel into an EPS level 3 masked bitmap use the a option. By use of o you can specify the alpha channel expresses opacity (default), t specifies transparency. Normally only pixels with 0 opacity are masked, all others are drawn. The alternative behaviour is to draw only pixels with full opacity and mask all others, this can be reached by option l.
Alpha channel support is available only if the bmeps library was configured for alpha channel support.
- PS level 1 printer:
dvips -I 1 ...
- PS level 2 grayscale printer with run-length- and ASCII-85-encoding
dvips -I 2gr8 ...
- PS level 2 color printer with run-length- and ASCII-85-encofing
dvips -I 2cr8 ...
I don't want to specifiy EPS output configuration on the command line each time. Can I configure default settings?
Both bmeps and the modified dvips retrieve default settings from the EPSOUTPUT environment variable before processing command line options.
The contents of the variable must be the same as the argument to the -I option of the modified dvips as explained in the section above.
This variable can be set in your login scripts, i.e.
setenv EPSOUTPUT 2gr8in .cshrc or
EPSOUTPUT=2gr8 export EPSOUTPUTin .profile or
set EPSOUTPUT=2gr8in AUTOEXEC.BAT.
Is there a template to see how things work? [Last Update: 2003/05/05]
Here I show a template how to use the bmeps with an
unmodified dvips.
\documentclass[ngerman,12pt,a4paper]{scrartcl} \usepackage{ngerman} \usepackage{ifpdf} \usepackage[latin1]{inputenc} \usepackage[T1]{fontenc} \usepackage{textcomp} \usepackage{mathptmx} \usepackage[scaled=.92]{helvet} \usepackage{courier} \usepackage{array} \usepackage{enumerate} \usepackage{longtable} \usepackage{latexsym} \usepackage[ngerman]{varioref} \usepackage{makeidx} \usepackage{color} \ifpdf \usepackage[activate=normal]{pdfcprot} \usepackage[pdftex]{graphicx} % % - The epstopdf package requires the write18 feature to invoke % eps -> pdf conversion from pdfLaTeX. To enable it use % - write18=enable in miktex.ini or % - shell_escape=1 in texmf.cnf or % - -shell-escape command line option % - on Windows there are errors if epstopdf is invoked by pdfLaTeX % (possibly the epstopdf program does not set stdout to binary mode?) % \usepackage{epstopdf} \pdfcompresslevel=9 \usepackage[ pdftex, a4paper=true, pdftitle={Test}, pdfsubject={Test}, pdfauthor={Dipl.-Ing. D. Krause}, colorlinks=true, linkcolor=linkgreen, pdfpagemode=None, pdfstartview=FitH ]{hyperref} \definecolor{linkgreen}{rgb}{0,0.5,0} \else \usepackage[dvips]{graphicx} \DeclareGraphicsRule{.png}{eps}{.bb}{`bmeps #1} \DeclareGraphicsRule{.jpg}{eps}{.bb}{`bmeps #1} \DeclareGraphicsRule{.jpeg}{eps}{.bb}{`bmeps #1} \DeclareGraphicsRule{.pgm}{eps}{.bb}{`bmeps #1} \DeclareGraphicsRule{.pbm}{eps}{.bb}{`bmeps #1} \DeclareGraphicsRule{.pnm}{eps}{.bb}{`bmeps #1} \DeclareGraphicsRule{.ppm}{eps}{.bb}{`bmeps #1} \usepackage[ dvips, colorlinks=true, linkcolor=linkgreen ]{hyperref} \definecolor{linkgreen}{rgb}{0,0.5,0} \fi \setlength{\parindent}{0cm} \author{Dipl.-Ing.~D.~Krause} \title{Test mit Bildformaten} \renewcommand*{\sectfont}{\bfseries} \makeindex \begin{document} \begin{sloppy} \newpage \section{Test} Dies ist ein Test für das Einfügen von Graphiken. \begin{figure} \begin{center} \caption{Delicate Arch} \includegraphics[width=0.9\linewidth]{arch5.jpg} \end{center} \end{figure} \end{sloppy} \end{document}
This template allows to use latex+dvips and pdflatex (latex+dvipdfm was not testet).
It is the template I use when writing new documents, maybee you need other packages and options.
The DeclareGraphicsRule is used only when not running pdftex/pdflatex/.
Troubleshooting
Why do I get dvips: ... Counldn't find ... file ...errors?
The dvips driver uses the kpathsea library to locate files.
This library assumes a directory structure having a so called BASEDIR.
Executable files are expected to be in BASEDIR/bin/<architecture>.
When searching for a file the library estimates the directory where
the executable for the current process was taken from, goes up two
directory levels and treats that directory as BASEDIR.
In BASEDIR/share/texmf there is a file ls-R containing the file name
database. This file is needed by kpathsea to find files.
Type
which dvipsto find where your dvips is located. If it is in a directory
BASEDIR/bin move it to BASEDIR/bin/<architecture>.
Why are pictures not converted?
Probably the original dvips is used. Type
dvips --versionIf the first output line looks like
dvips(k) 5.86you are using an unmodified dvips. If it looks like
dvips(k) 5.86 modified for bitmap graphics supportthe dvips version is correct.