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?
Download tetex-src.tar.gz from
ftp://ftp.dante.de/pub/tex/systems/unix/teTeX/current/distrib. Unpack the archive using
gzip -dc tetex-src.tar.gz | tar xf -Change into the texk sources directory using
cd tetex-src-2.0.2 cd texkMake 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.
Some notes about the Visual C++ runtime library:
There are at least 6 different versions of the runtime library:
C-compiler switch | Purpose |
---|---|
/ML | static, single-thread, release |
/MLd | static, single-thread, debug |
/MT | static, multi-thread, release |
/MTd | static, multi-thread, debug |
/MD | DLL, multi-thread, release |
/MDd | DLL, multi-thread, release |
The linker inspects the modules and tries to load support for all the run-time library versions found in all modules (even in modules in *.lib files). If different run-time library switches were used in some modules the linker complains about conflicts.
Conclusion: You need to compile all libraries and bmeps using the same compiler switch.
If you decide to use static libraries, I suggest "/MT", if you decide to build DLLs, use "/MD /GD" for the libraries and "/MD" for the application.
First we need to create the zlib library.
Copy the files from the Win32 subdirectory into the libraries top-level directory, modify the makefile "makefile.msc" (replace "/MD" by "/MT" if you want to build a static library), run nmake and copy the files into the appropriate places:
xcopy win32\*.* . /Y edit makefile.msc nmake -f makefile.msc zlib.lib xcopy *.lib \p\lib-stt\lib\ /Y xcopy *.h \p\lib-stt\include\ /YNow we can create the libpng library.
Here we have a makefile in the scripts subdirectory and a *.def file in the projects\msvc directory. Copy both files into the top-level directory, and edit the makefile. If you want to build a static library, replace the CFLAGS line by
CFLAGS= /nologo /MT /Oait -I\p\lib-stt-include /D "WIN32" /D "_WIN32" /D "NDEBUG" /D "_CONSOLE"to build a static library or use
CFLAGS= /nologo /MD /GD /Oait -I\p\lib-stt-include /D "WIN32" /D "_WIN32" /D "NDEBUG" /D "_CONSOLE"to build a DLL. Replace the section
libpng.lib: $(OBJS1) $(OBJS2) $(OBJS3) del libpng.lib lib libpng $(OBJS1) lib libpng $(OBJS2) lib libpng $(OBJS3)by
libpng.lib: $(OBJS1) $(OBJS2) $(OBJS3) -ERASE libpng.lib LIB /OUT:libpng.lib $(OBJS1) $(OBJS2) $(OBJS3)to build a static library.
To build a DLL use
libpng.lib: $(OBJS1) $(OBJS2) $(OBJS3) -ERASE libpng.lib -ERASE libpng.dll LINK /nologo /DLL /RELASE /INCREMENTAL:NO /SUBSYSTEM:CONSOLE /OUT:libpng.dll /IMPLIB:libpng.lib /DEF:png32ms.def $(OBJS1) $(OBJS2) $(OBJS3)instead.
Run
nmake -f makefile.msc libpng.lib xcopy *.lib \p\lib-stt\lib\ /Y xcopy *.dll \p\lib-stt\bin\ /Y xcopy *.h \p\lib-stt\include\ /Y
If you want JPEG support we need to create the JPEG library. The jpeg-6b directory contains a makefile named "makefile.vc" and a configuration header "jconfig.vc"
Edit the makefile, the CFLAGS and LDFLAGS lines should look like this
CFLAGS= /nologo /MT /W3 /O2 /D "WIN32" /D "_WIN32" /D "NDEBUG" /D "_CONSOLE" /I. /QI0f /QIfdiv LDFLAGS= /nologo /RELEASE /INCREMENTAL:NO /SUBSYSTEM:CONSOLECopy "jconfig.vc" to "jconfig.h", build and install the library.
copy jconfig.vc jconfig.h edit makefile.vc nmake -f makefile.vc libjpeg.lib xcopy *.lib \p\lib-stt\lib\ /Y xcopy *.h \p\lib-stt\include\ /YIf you want to create a DLL you need to create the file jpeg.def like this (you can copy and paste from here):
LIBRARY LIBJPEG DESCRIPTION 'The independent JPEG groups JPEG library' EXPORTS jpeg_std_error jpeg_CreateDecompress jpeg_stdio_src jpeg_read_header jpeg_start_decompress jpeg_abort jpeg_read_scanlines jpeg_finish_decompress jpeg_destroy_decompressThe "makefile.vc" should be changed to
CFLAGS= /nologo /MD /GD /W3 /O2 /D "WIN32" /D "_WIN32" /D "NDEBUG" /D "_CONSOLE" /I. /QI0f /QIfdiv LDFLAGS= /nologo /RELEASE /INCREMENTAL:NO /SUBSYSTEM:CONSOLE ... libjpeg.lib: $(LIBOBJECTS) -DEL libjpeg.lib -DEL libjpeg.dll -DEL *.obj LINK /DLL $(LDFLAGS) /OUT:libjpeg.dll /IMPLIB:libjpeg.lib /DEF:jpeg.def $(LIBOBJECTS)before building and installing the library.
If you want NetPBM support we need to create a pbm library. Change into the lib subdirectory. Copy the contents of the util subdirectory to here. Change the shhopt.c file, add the following contents:
char *rindex(char *s, int c) { char *back = NULL; char *ptr; ptr = s; while(*ptr) { if(*ptr == c) { back = ptr; } ptr++; } return back; }Change the libpm.c file, add the following contents:
#includeCreate a makefile "makefile.msc" as follows (you can copy and paste from here):#include #include static int _S_ISREG(int m) { int back = 0; if((m & _S_IFMT) == _S_IFREG) { back = 1; } return back; }
# Where do you want to install the software? PREFIX=c:\p\lib-stt # Which programs to use for compiling and linking? CC=CL LD=LINK # Where is Visual C? # Directories lib, include and bin must be beyound this. VC=C:\Programme\DevStudio\Vc all: lib install: all -mkdir $(PREFIX) -mkdir $(PREFIX)\include -mkdir $(PREFIX)\lib -mkdir $(PREFIX)\bin xcopy *.h $(PREFIX)\include\ xcopy ..\*.h $(PREFIX)\include\ xcopy *.lib $(PREFIX)\lib\ clean: -del *.obj -del *.lib -del *.exe -del *.dll lib: netpbm.lib OBJS= libpm.obj bitio.obj colorname.obj \ libpbm1.obj libpbm2.obj libpbm3.obj libpbm4.obj libpbm5.obj \ libpgm1.obj libpgm2.obj \ libppm1.obj libppm2.obj libppmcmap.obj libppm4.obj libppm5.obj \ libppmfloyd.obj \ libpnm1.obj libpnm2.obj libpnm3.obj \ libpam.obj libpammap.obj nstring.obj shhopt.obj netpbm.lib: $(OBJS) lib /nologo /out:netpbm.lib $(OBJS) COBJFLAGS= /nologo /MT /W3 /GX /O2 /D "WIN32" /D "_WIN32" /D "NDEBUG" /D "_CONSOLE" /YX /FD /I. /I.. /I"$(VC)\Include" $(SCD) $(DEFS) /QI0f /QIfdiv .c.obj: $(CC) $(COBJFLAGS) /c $*.c
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
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
Using bmeps with LaTeX
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 #1}or
\DeclareGraphicsRule{.png}{eps}{.bb}{`bmeps -p2 -c #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.
How do 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 % - -shell-escape command line option (recommended) % - write18=enable in miktex.ini or (not recommended, security risk) % - shell_escape=1 in texmf.cnf or (not recommended, security risk) % - 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/.
Using bmeps with other applications
How can I export MS Excel charts to EPS using bmeps?
A VB macro ChartPict_save() -
placed in
contrib/kant_krishna/excel_to_eps.vbs
-
was provided by Krishna Kant to export all charts to
PNG files and run bmeps on these files.
Note (1): This macro is provided "as-is", no support for it as
I have no knowledge of VB. On my Office 97 Prof. it did not
work, maybee it needs a more recent Office version.
Note (2): This conversion produces bitmap graphics EPS files.
Possibly you want to try exporting to WMF and use the wmf2eps program
to obtain vector graphics EPS files.
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.