bmeps + dvips add-on

FAQ

Basics
- What is bmeps?
- Which filetypes are supported?
Installation
Usage
Troubleshooting
- Why do I get dvips: ... Couldn't find... errors?
- Why are pictures not converted?

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

PNG is the "native" file format because

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 PNG file format is a good choice for for "artificial" pictures such as logos, screenshots and computer drawings.

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.eps

The 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://www.e-technik.fh-schmalkalden.de/personen/dhp/krause under
Software / BMEPS + dvips add-on. From the Installation section download

bmeps.tgz.

What other software is required to install bmeps?
You need to install

zlib and
libpng
jpegsrc.v6b (optional)
netpbm-9.2 (optional)

before you can install bmeps.
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 install

Make sure to set the environment variable CFLAGS and LDFLAGS properly.

Should I build a modified dvips driver?
This depends on your situations.
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 install

Now go into the dvipsk-* directory and run

	./configure ...
	make
	make install

Possibly 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 install

again 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

to the project. Build the project.

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

to the project and build the library.

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

to the project.
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>

  #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

to the project.
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

Now you are ready to build the application.

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 600

directly 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.bb

to 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

    \ifx\pdfoutput\undefined \newcount\pdfoutput \fi
    \ifcase\pdfoutput \DeclareGraphicsRule{.png}{eps}{.bb}{} \fi

for modified dvips or

    \ifx\pdfoutput\undefined \newcount\pdfoutput \fi
    \ifcase\pdfoutput \DeclareGraphicsRule{.png}{eps}{.bb}{`bmeps #1} \fi

for unmodified dvips.

If your document contains EPS graphics too, you should change

    \includegraphics[...]{xxx.eps}

    \includegraphics[...]{xxx}

and provide both an EPS and a PDF version of the picture.
Use

    ps2pdf xxx.eps xxx.pdf

or - for large pictures -

    cat xxx.eps | epsffit -c 87 92 487 363 | ps2pdf - xxx.pdf

to convert the EPS file to PDF.
The epsffit program is contained in the psutils.
The ps2pdf script is contained in the Ghostscript distributions.

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 images 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.

Examples:

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.

Examples:

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 2gr8

in .cshrc or

	EPSOUTPUT=2gr8
        export EPSOUTPUT

in .profile or

	set EPSOUTPUT=2gr8

in AUTOEXEC.BAT.

Is there a template to see how things work? [Last Update: 2002/04/30]
Here I show a template how to use the bmeps with an unmodified dvips.

%
%	%Z% %G% %I% %M%
%
\documentclass[ngerman,12pt,a4paper]{scrartcl}
\usepackage{ngerman}
\newif\ifpdf\ifx\pdftexversion\undefined\pdffalse\else\pdftrue\fi
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage{mathptmx}
%
% scaled=.92 requires PSNFSS 8.0
% for older PSNFSS versions try \usepackage{helvet}
%
\usepackage[scaled=.92]{helvet}
\usepackage{courier}
\usepackage{array}
\usepackage{enumerate}
\usepackage{longtable}
\usepackage{latexsym}
\usepackage[ngerman]{varioref}
\usepackage{makeidx}
\usepackage{color}
\ifpdf
\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
\parindent0cm
\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 dvips

to 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 --version

If the first output line looks like

	dvips(k) 5.86

you are using an unmodified dvips. If it looks like

	dvips(k) 5.86 modified for bitmap graphics support

the dvips version is correct.

_{Dirk Krause d.krause@e-technik.fh-schmalkalden.de 2002/09/03} ^{http://www.e-technik.fh-schmalkalden.de/personen/dhp/krause/pages/software/bmeps/faq.html}