# bmeps 2.1.2

- Overview
- Download / Installation
- Usage
- Examples
- bmeps GUI
- mkpdfsls
- FAQ
- Change log
- Other projects
- PDF manual (en)
- PDF manual (de)
- Doxygen docu

## Example

- Example data
- Example image
- Example LaTeX source
- Convert files before running LaTeX
- PS level 1
- PS level 2
- PS level 2 over colored background
- Mixing against the background color
- PS level 3 and image mask
- PDF and alpha channel transfer
- Convert files ``on the fly''
- Make sure dvips is running in secure mode by default
- Use \DeclareGraphicsRule
- Create the bounding boxes
- Set up draft mode
- Run latex and dvips
- Deactivate draft mode, run final dvips

### Example data

#### Example image

In the examples we use a partially transparent PNG file fbt.png containing a clock showing 5 minutes before 12. The image contains a radial alpha gradient, it is fully opaque in the center and fully transparent in the corners. The table below shows the image in front of different background colors.

#### Example LaTeX source

The LaTeX source for the examples is a one-foil beamer presentation:

    \documentclass{beamer}
    \mode<presentation>{\usetheme{Madrid}
    \setbeamercovered{transparent}}
    \usepackage[german]{babel}
    \usepackage[latin1]{inputenc}
    \usepackage[T1]{fontenc}
    \usepackage{ifpdf}
    \usepackage{graphicx}
    \usepackage{color}
    \ifpdf
    \hypersetup{pdfpagemode=FullScreen}
    \fi
    \title[Beamer and bmeps]{Using bmeps with the beamer class}
    \author[Krause]{D.~Krause}
    \subject{bmeps}
    \begin{document}
    % \beamertemplateshadingbackground{yellow!50}{magenta!50}
    \begin{frame}
    \frametitle{Image over white background}
    \includegraphics[width=5cm]{fbt1}
    \end{frame}
    \end{document}

While processing the examples we will change the background to yellow and later into a blue-to-yellow transition, the file name of the included graphics also changes.

### Convert files before running LaTeX

#### PS level 1

The commands

    bmeps -leps1 fbt.png fbt1.eps
    latex bt1 && latex bt1 && latex bt1 && dvips bt1

produce EPS level 1 output and use the file in the presentation.

#### PS level 2

The commands

    bmeps -l eps2 fbt.png fbt2.eps
    latex bt2 && latex bt2 && latex bt2 && dvips bt2

produce EPS level 2 output. The output is colored now, but the file size is much smaller than fbt1.eps because PS level 2 provides better compression and encoding algorithms.

#### PS level 2 over colored background

If we change the presentations background color to yellow and run

    bmeps -l eps2 fbt.png fbt3.eps
    latex bt3 && latex bt3 && latex bt3 && dvips bt3

the image of the background is unchanged white because the colors in the EPS file did not change.

#### Mixing against the background color

The yellow color is expressed hexadecimally as 0xff, 0xff and 0x7f. The conversion to the range [0;1] results in 1, 1, 0.5.
To create fbt3.eps we mix against a background color (m=y), the default background color is 1:1:0.5 (b=1.0:1.0:0.5) and the default background color is always used (a.u.d.b=y) ignoring background color information from the input file.

    bmeps -leps2,m=y,b=1.0:1.0:0.5,a.u.d.b=y fbt.png fbt4.eps
    latex bt4 && latex bt4 && latex bt4 && dvips bt4

#### PS level 3 and image mask

Now we use a blue-to-yellow transition as background in the presentation. In addition to mixing the alpha channel from the input file is converted into an image mask.

    bmeps -leps3,m=y,b=1.0:1.0:0.5,a.u.d.b=y,c.i.m=y fbt.png fbt5.eps
    latex bt5 && latex bt5 && latex bt5 && dvips bt5

#### PDF and alpha channel transfer

To make the image partially transparent (the presentation background is partially visible through the image) we need to transfer the alpha channel to the output. This is possible for PDF level 1.4 output only.
First we include the fbt.png image directly

    \documentclass{beamer}
    \mode{\usetheme{Madrid}
    \setbeamercovered{transparent}}
    \usepackage[german]{babel}
    \usepackage[latin1]{inputenc}
    \usepackage[T1]{fontenc}
    \usepackage{ifpdf}
    \usepackage{graphicx}
    \usepackage{color}
    \title[Beamer and bmeps]{Using bmeps with the beamer class}
    \author[Krause]{D.~Krause}
    \subject{bmeps}
    % ----- The next line is important when dealing with alpha channels
    \pdfpageattr {/Group << /S /Transparency /I true /CS /DeviceRGB>>}
    \begin{document}
    \beamertemplateshadingbackground{yellow!50}{blue!50}
    \begin{frame}
    \frametitle{Image over color gradient background}
    \includegraphics[width=5cm]{fbt.png}
    \end{frame}
    \end{document}

and run

    pdflatex bt6 && pdflatex bt6 && pdflatex bt6

The result
shows that recent versions of pdflatex handle PNG file correctly. (In previous versions areas with alpha=0 were converted to black).
To include a PDF file created by bmeps we change the LaTeX source to

    \documentclass{beamer}
    \mode{\usetheme{Madrid}
    \setbeamercovered{transparent}}
    \usepackage[german]{babel}
    \usepackage[latin1]{inputenc}
    \usepackage[T1]{fontenc}
    \usepackage{ifpdf}
    \usepackage{graphicx}
    \usepackage{color}
    \title[Beamer and bmeps]{Using bmeps with the beamer class}
    \author[Krause]{D.~Krause}
    \subject{bmeps}
    % ----- The next line is important when dealing with alpha channels
    \pdfpageattr {/Group << /S /Transparency /I true /CS /DeviceRGB>>}
    \begin{document}
    \beamertemplateshadingbackground{yellow!50}{blue!50}
    \begin{frame}
    \frametitle{Image over color gradient background}
    \includegraphics[width=5cm]{fbt7.pdf}
    \end{frame}
    \end{document}

and run

    bmeps -lpdf fbt.png fbt7.pdf
    pdflatex bt7 && pdflatex bt7 && pdflatex bt7

Both PDF files look nearly the same. The difference -- the PDF version of the image has interpolation turned on -- is visible only when zooming into the presentation and comparing the two included images. The first foil includes the PNG image, no interpolation flag is used. The second foil includes the PDF image, the interpolation is turned on. When switching between the foils look at the edges of the clock pointers and the 5-minutes-markers to see the difference.
For both versions the line

    \pdfpageattr {/Group << /S /Transparency /I true /CS /DeviceRGB>>}

is necessary to avoid the use of CMYK as colorspace in alpha calculations (this would lead to color shifting).

### Convert files ``on the fly''

#### Make sure dvips is running in secure mode by default

The configuration file for dvips is in the texmf tree in ${texmf}/dvips/config/config.ps.
Make sure the entry

    z1

is active (not commented out).
The execution of external commands by dvips is a security risk. We are willing to take that risk for *.dvi files created by ourselves from *.tex files we created, but not in general.

#### Use \DeclareGraphicsRule

Change the LaTeX source to

    \documentclass{beamer}
    \mode<presentation>{\usetheme{Madrid}
    \setbeamercovered{transparent}}
    \usepackage[german]{babel}
    \usepackage[latin1]{inputenc}
    \usepackage[T1]{fontenc}
    \usepackage{ifpdf}
    \usepackage{graphicx}
    \usepackage{color}
    \ifpdf
    \hypersetup{pdfpagemode=FullScreen}
    \else
    \DeclareGraphicsRule{.png}{eps}{.bb}{`../bmeps #1}
    \fi
    \title[Beamer and bmeps]{Using bmeps with the beamer class}
    \author[Krause]{D.~Krause}
    \subject{bmeps}
    \begin{document}
    \beamertemplateshadingbackground{yellow!50}{yellow!50}
    \begin{frame}
    \frametitle{Image over transient background}
    \includegraphics[width=5cm]{fbt.png}
    \end{frame}
    \end{document}

The \DeclareGraphicsRule{.png}{eps}{.bb}{`bmeps #1} command tells LaTeX that PNG (*.png) files can be converted to EPS. The bounding box information for such files can be found in a file with the same name but the suffix ``.bb''. For the image fbt.png we have to create a file fbt.bb.
If you use a modified dvips (bmeps support added) use a

    \DeclareGraphicsRule{.png}{eps}{.bb}{}

rule. Dvips does not need to run an external program, it just invokes the library function from libbmeps.

#### Create the bounding boxes

To create the bounding box files for all images in the current directory run

    bmeps -lbb .

#### Set up draft mode

As long as we are editing the document we should set bmeps to draft mode to run dvips as fast as possible. We can either save the configuration name as a permanent option or use the EPSOUTPUT environment variable. I recommend to use the EPSOUTPUT environment variable because this only affects work in the one terminal:

    export EPSOUTPUT="eps2,d=y"

#### Run latex and dvips

Now we can run latex and dvips (in the same terminal where the EPSOUTPUT variable is set) as often as needed.
The ``-R0'' option is not needed when using a modified dvips (bmeps support added).

    latex bt8 && latex bt8
    dvips -R0 bt8

#### Deactivate draft mode, run final dvips

To deactivate draft mode either remove the EPSOUTPUT environment variable or close the terminal and open a new one where EPSOUTPUT is not defined.
Alternatively use

    export EPSOUTPUT="eps2"

We can now create the final version of the document using

    dvips -R0 bt8