bmeps - convert PNG/JPEG/NetPBM to EPS

# bmeps |
| Convert PNG/JPEG/NetPBM to EPS

Overview / Installation / Usage / FAQ / Change Log

## FAQ | PDF manual "bmeps.pdf" available

| Basics
|  | What is bmeps?
|  | Which filetypes are supported?
| Installation
|  | Where can I get it?
|  | What other software is required?
|  | How to install the bmeps library?
|  | Should I build a modified dvips driver?
|  | How do I build the modified dvips driver?
|  | I'm on a Win32 system. Is there a binary?
|  | I'm on a Win32 system. How can I build bmeps.exe?
|  | Where can I get a Win32 binary of the modified dvips?
| Usage
|  | What must I do in my LaTeX source to use bitmap graphics?
|  | What's the .bb file for?
|  | How can I build the .bb file?
|  | Can I use PNGs with both latex/dvips and pdflatex?
|  | Which options are recognized by bmeps?
|  | How can I use bitmap graphics with the modified dvips?
|  | I don't want to specifiy EPS output configuration on the command line each time. Can I configure default settings?
|  | Is there a template to see how things work?
| 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://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)

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

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`

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

        \usepackage{ifpdf}
        \ifpdf
        ...
        \else
        \DeclareGraphicsRule{.png}{eps}{.bb}{}
        \fi

for modified `dvips` or

        \usepackage{ifpdf}
        \ifpdf
        ...
        \else
        \DeclareGraphicsRule{.png}{eps}{.bb}{`bmeps #1}
        \fi

for 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.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 (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.

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