Dirk Krause's tools 2.2.24

Get Dirk Krause's tools at SourceForge.net. Fast, secure and Free Open Source software downloads.
 

bmeps

This program will be replaced by the bmpp program in dktools version 3.
The development of bmpp is completed, it is available in the 3-preview archives.
The recent binary installation file for Windows - dktools-win32-*.exe - contains the program.

Overview

Data flow for bmeps

The program converts bitmap images (PNG, JPEG, TIFF) to EPS and PDF and produces bounding box files for use with LaTeX.
Tiff files can be read if the TIFFReadRGBAImage() function from the TIFF library can open them.

The program produces EPS level 1, 2 and 3 and PDF level 1.2, 1.3 and 1.4.
Depending ont the PS level the following compression and encoding mechanisms can be used:

  • ASCII-Hex encoding
  • ASCII85 encoding (requires at least PS level 2)
  • DCT-pass-through of JPEG files (requires at least PS level 2)
  • flate compression (requires at least PS level 3)

Manuals

Usage

Quick start

To convert an image to EPS level 2 use

bmeps -a -leps image.png

or

bmeps image.png image.eps

To convert an image to PDF use

bmeps -a -lpdf image.png

or

bmeps image.png image.pdf

To create a bounding box file for an image use

bmeps -a -lbb image.png

or

bmeps image.png image.bb

Options in detail

Configuration mechanism

Bmeps has too many settings to type them as command line options each time bmeps is started.
On the command line you have to use the ``-l'' option to specify the name of one configuration (a collection of configuration entries). Some configurations are built-in, you can define additional configurations in a configuration file.
A command line option ``-o'' is available to overwrite a configuration entry on the command line.
If no configuration name is specified bmeps searches for a default configuration name previously configured and inspects the EPSOUTPUT environment variable. The EPSOUTPUT environment variable has higher priority than the default configuration name.

Configuration file location and structure

The configuration file is named ${sysconfdir}/bmeps/bmeps.conf on Linux and UNIX systems, ${sysconfdir} is the directory for system configuration data (i.e. /etc or /usr/local/etc). On Windows systems the configuration file is %WINDIR%\bmeps\bmeps.conf.
The file consists of a list of configuration sections, each section describes one configuration.
Each section is started by the configuration name in square brackets. The remainder of the section is a list of key/value pairs one per line.
To create a configuration for a grayscaled PS2-printer we could write the section as follows:

[myprinter:ps2]
color = no

Abbreviations can be used for the configuration entry names. I recommend to write the full names in configuration files for readability. The abbrevitations should be used only when typing commands.

Configuration entries

In this list both the full name and the abbreviation is shown for each command.

  • output type = string
    o.t
    defines the output type, either ``ps'', ``pdf'' or ``bb'' (for LaTeX bounding boxes).
  • level = string
    l
    the output level, either ``1'', ``2'' or ``3'' for PS or ``1.2'', ``1.3'' or ``1.4'' for PDF output.
  • color = boolean
    c
    flag, whether to create colored or grayscaled output.
    Note: PS level 1 only allows grayscaled output.
  • dsc comments = boolean
    dsc.c
    flag, whether or not to write DSC comments to PS/EPS output.
  • encoding = string
    e
    the list of allowed encoding, the encodings are separated by colon. Abbrevations can be used, i.e. ``a:r:d'' instead of ``ascii85:run-length:dct''.
    The following encodings can be used:
    • ascii85
      a
      ASCII85 encoding. If ASCII85 is not allowed, bmeps uses ASCII-Hex encoding.
    • run-length
      r
      run-length encoding.
    • flate
      f
      flate compression.
    • dct
      d
      DCT compression. Bmeps does not DCT-encode data, but it can use DCT-encoded data from JPEG files.
    Note: The compression/encoding mechnisms available depend on the output type and output level. Not all combinations are possible.
  • multiple data sources = boolean
    m.d.s
    flag, causes separated data in PS/EPS output. This allows to run-length compress areas and horizontal lines in the same color.
  • predictor = string
    chooses a predictor for flate compression when producing a PDF file. The predictor can be one of ``none'' (no prediction), ``tiff'' (TIFF sub prediction), ``png-sub'' (PNG sub prediction), ``png-up'' (PNG up prediction), ``png-average'' (PNG average prediction) or ``png-paeth'' (prediction as suggested by Alan W. Paeth).
    For typical PNG images (i.e. screenshots, logos, diagrams...) there is no need to use a predictor. For special cases (i.e. photos saved as PNG or images containing color gradients) the use of a predictor can decrease the output file size of the PDF file significantly (compared against a PDF file created without using a predictor).
    The predictor to use strongly depends on the source image.
  • mix = boolean
    m
    flag, activates mixing. If an input image contains an alpha channel, opacity can be used to mix against a background color. If the image contains a background color chunk bmeps uses the background color from the file. Otherwise the default background color is used.
  • background = RGB-triple
    b
    the default background, specified as RGB-triple. The RGB-triple consists for real numbers in the range [0;1], i.e. ``1.0:1.0:0.5'' for magenta.
  • always use default background = boolean
    a.u.d.b
    a flag, telling to skip the background color chunk from the input file. If this flag is set, the default background is always used.
  • create image mask = boolean
    c.i.m
    a flag to specify whether or not to create an image mask. In addition to mixing against a background color the alpha channel data can also be used to create an image mask.
  • image mask trigger level = real
    i.m.t.l
    the trigger level to create an image mask, specified in the range [0;1]. All pixels having opacity>=level are drawn, all other pixels are masked.
  • transfer alpha channel = boolean
    t.a.c
    flag, passes alpha channel data from input through to ouput. This is only possible when creating PDF-1.4 output. Transferring the alpha channel automatically deactivates mixing and image mask creation.
  • allow pdf page attributes = boolean
    a.p.p.a
    flag, allows to create PDF page attributes.
    You should allow the creation of PDF page attributes when transferring an alpha channel to PDF output when you output is intended to be viewed standalone.
  • interpolate = boolean
    i
    flag, whether or not to enable image interpolation in the output file.
  • jpeg interpolate = boolean
    j.i
    flag, whether or not to enable image interpolation for DCT-encoded images too.
  • use resolution chunk = boolean
    u.r.c
    flag, indictates whether or not to use image resolution data from input file to scale output.
  • media size = string
    m.s
    paper size to fit. The paper size can be specified:
    • by paper format name: ``A3'', ``A4'', ``A5'', ``B4'', ``B5'', ``Letter'', ``Legal'', ``Tabloid'', ``Ledger'', ``Statement'', ``Executive'', ``Folio'', ``Quarto'' or ``10x14''.
    • using 4 values: x0, y0, x1, and y1 (the lower left and upper right point).
    • using 8 values: bbx0, bby0, bbx1, bby1, ix0, iy0, ix1, iy1. The bb...-values specify the bounding box, the i...-values the area used for the image. The i...-rectangle must reside inside the bb...-rectangle.
  • pdf fit = string
    p.f.
    zoom factor when opening the PDF output image, either ``width'', ``height'' or ``page''.
  • draft = boolean
    d
    flag, activates/deactivates draft mode. In draft mode bmeps only read the input image dimensions and write a placeholder rectangle to the output.
  • showpage = boolean
    sh
    flag, controls the use of the showpage operator in PS output. PS/EPS images for standalone viewing and printing should have a showpage operator.
    Images for inclusion in LaTeX or other DCT applications... should not contain a showpage operator.
  • operator dictionary = boolean
    o.d
    flag, controls whether or not to use the dictionary-argument version of the PS image/colorimage operator.
  • separated dictionary = boolean
    s.d.
    flag, controls the use of a separated dictionary in output. This prevents the output image from overwriting entries in the PS dictionary of the including document, so it is recommended when creating output images for inclusion in documents.
  • vmreclaim = boolean
    v
    flag, controls the use of ``1 vmreclaim'' at the end of PS output. This requires the separated dictionary.
  • jfif sof set = string
    j.s.s
    the list of allowed SOF markers in DCT encoded output. Entries are separeted by colon.
Example configuration entry

An example configuration entry might look like this:

[copy_of_ps2]
output type                     = ps
level                           = 2
interpolate                     = yes
color                           = yes
multiple data sources           = yes
dsc comments                    = yes
encoding                        = ascii85:run-length:dct
mix                             = yes
background                      = 1.0:1.0:1.0
always use default background   = yes
create image mask               = no
image mask trigger level        = 0.000001
transfer alpha channel          = no
showpage                        = no
operator dictionary             = yes
separated dictionary            = yes
vmreclaim                       = no
draft                           = no
jfif sof set                    = 0:1
jpeg interpolate                = no
use resolution chunk            = no
# No media size specified -> 1 pixel = 1 PS point
# media size
# No PDF zoom factor, we create PS output
# pdf fit
Command line syntax

The following commands can be used to run bmeps:

  • bmeps [<options>] [<inputfile> [<outputfile>]]
    processes the input file and write the output file. If no output file is specified bmeps writes to standard output. If no input file is specified bmeps reads input from standard input, the ``-t'' option must be used to choose a file type.
  • bmeps [<options>] [<directory>]
    runs bmeps on a directory. Bmeps searches for the directory for files it can handle and processes these files.
  • bmeps -h
    shows a help text.
  • bmeps -v
    shows version number and license conditions.
  • bmeps -c -l...
    save the configuration (argument to the ``-l'' option) as default.
  • bmeps -C
    shows the current configuration.
  • bmeps -u
    removes the default configuration.

The following command line options can occure:

  • -lconfiguration
    specifies the name of the configuation to use, either a built-in one (``eps'', ``eps1'', ``eps2'', ``eps3'', ``ps'', ``ps1'', ``ps2'', ``ps3'', ``pdf'', ``pdf12'', ``pdf13'', ``pdf14'', ``faxpdf'') or a configuration from the configuration file.
    A list of configuration entries to overwrite can be appended using the comma as separator, i.e.
    -leps2,color=no
    Abbreviations can be used to overwrite configuration entries:
    -leps2,c=n
    If the -l option is omitted, bmeps chooses a configuration as follows:
    • If the output file name ends on ``.eps'', ``.ps'', ``.pdf'' or ``.bb'' the configuration ``eps'', ``ps'', ``pdf'' or ``bb'' is used. Note: All -o options (see below) must be placed after the output file name.
    • The EPSOUTPUT environment variable is checked. If it exists, it contains the name of the configuration to use.
    • The ``/language'' preference (permanent option) is checked.
  • -okey=value
    can be used to overwrite configuration entries, i.e.
    -o color=no
    Abbreviations can be used:
    -o c=n
    Note: -o configuration entry overwrites are not saved by the -c option, only configuration entry overwrites in the -l option.
  • -fnumber
    -fnumber-number
    specify the frame(s) to convert if the input image contains multiple frames (i.e. TIFF files). By default bmeps converts all frames.
  • -m
    -m-
    activates/deactivates make mode. If bmeps is run on a directory it checks the directory for files it can handle. If make mode is turned off, a conversion is run for each acceptable input file.
    In make mode bmeps starts a conversion only if there is not conversion output file or if the conversion output file is not up to date.
  • -a
    automatically creates an output file name based on the input file name and the output driver if only the input file name is specified.
    By default bmeps write output to standard output if not output file name is given. The ``-a'' option can be used like 
    bmeps -a -lbb picture.png
    to create the picture.bb file.
  • -A
    -A-
    suppresses/enables the notification about alpha channels transferred from PNG or TIFF to PDF.

Examples

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.

Image five before twelve Image five before twelve on blue background Image five before twelve on red background
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.
Screenshot: PS level 1

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.
Screenshot: PS level 2

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.
Screenshot: PS level 2, background color

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

Screenshot: PS level 2, mixing against background

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

Screenshot: PS level 3, image mask

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<presentation>{\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
Screenshot: PDF, mixing against background color
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<presentation>{\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

Screenshot: PDF with alpha channel
 
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

Screenshot: Draft mode

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

mkpdfsls.pl

Overview

A user requested additional functionality to create a PDF presentation (i.e. to show holiday photos) from a list of images in one simple step.
I do not like to program this in C in the bmeps source code, so I wrote a Perl script instead.

There are three general ways to produce a slide show using mkpdfsls.pl:

  • Convert each image file to PDF and use pdftk to bundle the images in one PDF file.
    The ``pdftk'' program is required.
  • Convert each image to PDF, create a LaTeX source referencing these images and run LaTeX. The resulting PDF file attempts to change to full-screen mode and just shows the images.
    A LaTeX distribution is required.
  • Convert each image to PDF, create a LaTeX source referencing these images and run LaTeX. The resulting PDF file attempts to change to full-screen mode and shows the images in a presentation where each slide shows the image, a description, a slide show name and the authors name.
    A LaTeX distribution and the ``beamer'' class for LaTeX are required.

To run the mkpdfsls.pl script you must have Perl installed.

The project file

The project file consists of an optional ``[options]'' section to set options and a ``[files]'' section listing the images and optionally short descriptions for the images.

The [options] section

The options section is optional and can be used for setup and can contain the following entries:

  • presentation maker = maker
    chooses one of the ways to create the final PDF file.
    Use either ``pdftk'', ``plain'' or ``beamer''.
  • theme = theme
    chooses a beamer theme, i.e. ``Madrid''. Only used if ``presentation maker = beamer''.
  • background = color
    chooses a background color. Specify one of the color names defined in the xcolor package, i.e. ``black''. Only used if ``presentation maker = beamer''.
  • input encoding = encoding
    specifies an input encoding for use with LaTeX, i.e. ``latin1'' or ``utf8''.
    By default the mkpdfsls.pl script inspects the LANG environment variable and uses ``utf8'' if the variable ends on ``.UTF-8'', ``latin1'' otherwise.
    Only used if ``presentation maker = beamer'' or ``plain''.
  • babel options = options
    chooses options for the babel package.
    Only used if ``presentation maker = beamer''.
  • author = author
    specifies the slide show author.
    Only used if ``presentation maker = beamer''.
  • title = title
    specifies a title for the slide show.
    Only used if ``presentation maker = beamer''.
  • make mode = flag
    turns make mode on or off.
    In make mode the script only converts images to PDF if necessary (if the PDF file does not yet exist or is older than the source image).
    The make mode is enabled by default.
  • use exif = flag
    enables/disables the use of ``Comment'' EXIF tags in JPEG files as image descriptions.
    Note: The Image::ExifTool and DKrause::LaTeXEncoder Perl modules are needed.
The [files] section

The files section lists the source image files to use, one per line.
You can specify optional comments, separate file name and comment by ``=''.

Example file
[options]
presentation maker      =       beamer
theme                   =       Madrid
background              =       black
author                  =       John Doe
title                   =       Holidays in Scotland
use exif                =       yes
# input encoding is not explicitly specified, inspect LANG variable
# No babel options -> No use of babel package
# make mode not specified, enabled by default

[files]
scot01.jpg
scot02.jpg
scot03.jpg

Running mkpdfsls.pl

Create a project file, i.e. ``holiday.mks'' and run

mkpdfsls.pl holiday.mks

FAQ

General usage

How do I create an EPS file?
bmeps -leps input.png output.eps
How do I create a PS file?
bmeps -lps input.png output.ps
How do I create a PDF file?
bmeps -lpdf input.png output.pdf
How do I create a bb file?
bmeps -lbb input.png output.bb
What are the easiest to use bmeps command lines?

The most simple way to convert an input image to EPS, PS, PDF or bb using bmeps is to run one of the commands

bmeps input.png output.eps
bmeps input.png output.ps
bmeps input.png output.pdf
bmeps input.png output.bb

Note: If the ``-l'' option is omitted bmeps inspects the output file name suffix to find an appropriate output configuration. If you want to overwrite configuration entries using the ``-o'' option, place these options after the output file name.

Why should I avoid forward-and-backward conversion?

You might loose information (this means the result is not looking exactly as the original) when doing unnecessary forward-and-backward conversions for three reasons:

  • Image interpolation
    If the image interpolation flag is set in an EPS or PDF file the viewer or renderer is allowed to modify the image for a better rendering quality. The interpolation flag is enabled by default for EPS2, EPS3 and PDF output.
    You can disable the interpolation flag using the option: 
    -o i=n
  • Limitations of computer mathematics.
    Imagine -- for example -- an image having a resolution chunk telling the image is at 216 dpi. Both EPS and PDF output require a scale operation using the factor 1/3.
    This can be written as a 0.33333... (with an endless number of digit 3).
    Bmeps uses a C variable of type "double" to store the scale factor, this data type can not store numbers of infinite length. When printing a double value to file the fprintf() function prints a limited number of digits only.
  • Limitations in file formats.
    Some file formats use resolution units not based on inches (i.e. dots per meter or dots per centimeter) and save the result as integer values. Forward and backward conversions will loose the digits after the decimal dot.
    See also Should I use the resolution chunk?.

So if you convert an image img1.png to img1.eps and then img1.eps to test.png the files img1.png and test.png will not necessarily be 100 percent equal.

What is ``image interpolation''?

If the interpolation flag is set to true for an image EPS and PDF viewers are allowed to attempt quality improvements for better on-screen rendering.
The bt9.pdf file shows the effect. The first foil includes a PNG file (without interpolation flag set), the second foil includes a PDF file (interpolation flag is set to ``true''). When switching between the foils look at the edges of the 5-minutes-circles and the edges of the pointers.

What is a ``predictor'', should I use it?

Prediction is a technique used in combination with flate compression and LZW compression (not available in bmeps) to produce smaller output files. Instead of passing each color value to flate compression directly a prediction for the color value is calculated, the difference between the current color value and the predicted value is passed to the flate compression.
Different prediction mechanisms can be used:

tiff The predicted value is the same as the corresponding value from the point to the left.
This predictor can be used with any number of bits per component.
png-sub All the png-... predictors can be used with 8 bits per component or 16 bits per component only.
The predicted value for each byte is the value of the corresponding byte from the point to the left.
png-up The predicted value for each byte is the value of the corresponding byte from the point one row above.
png-average The predicted value for each byte is the average of the corresponding bytes from the point to the left and the point one row above.
png-paeth The predicted value for each byte is calculated from the corresponding bytes of the point at the left, the point above and the point left above. See RFC 2083 for the calculation algorithm.

The color values and byte values for unavailable points (left from column 0 or above row 0) are 0.

For ``normal'' PNG images like screenshots, logos... there is no need to use a predictor.
For very special cases (i.e. photos saved as PNG, not JPEG or for images containing color gradients) you will need a predictor.
General rule: If you convert a PNG to PDF and the file size increases significantly more than 25 % you should attempt to use a predictor.
The predictor to use depends on the input image, so you should attempt different predictors to find the best possible result.
I suggest to attempt ``tiff'' and ``png-paeth'' first, in my tests they showed the best results.

Why are the PDFs produced by bmeps larger than the source PNGs and JPEGs?

Normally the PDFs produced by bmeps are ~25 percent larger than the original PNG or JPEG file because bmeps does not save binary data. Binary data is encoded ASCII-85 to ensure I can open the files produced by bmeps in a text editor. This allows me to inspect the PDF files for debugging.

In addition to flate compression the PNG file format allows the use of palettes and predictors.
Palettes are not available in PDF (at least I did not find them in the PDF 1.4 specification). Predictors can be used with bmeps when producing PDFs, but you can only specify one predictor which is used for all image rows. In PNG files predictors can be specified for rows.

How can I create a PDF containing the compressed image as binary data (not ASCII-85 encoded)?

You need additional software, Multivalent from http://multivalent.sourceforge.net and a Java run-time environment (JRE), I suggest to use the current version from http://java.sun.com.
Save the Multivalent.jar file, i.e. as ``/usr/local/Multivalent/Multivalent20060102.jar'' and run

JO='-Xms64m -Xmx1024m'
CP='-classpath /usr/local/Multivalent/Multivalent20060102.jar'
java $JO $CP tool.pdf.Compress -compatible file.pdf

to pack ``file.pdf'' to ``file-o.pdf''.

Using bmeps with LaTeX

What must I do in my LaTeX source to use bitmap graphics?

When using an unmodified dvips add

\DeclareGraphicsRule{.png}{eps}{.bb}{`bmeps #1}

to your LaTeX preamble.
Now dvips attempts to run the bmeps program for each included image using the default options configured by ``bmeps -c ...''.
Alternatively you can use

\DeclareGraphicsRule{.png}{eps}{.bb}{`bmeps -leps2 #1}

to set the EPS version.
When running dvips make sure to allow the execution of external commands.

When using the modified dvips add

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

to the document preamble.

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 -lbb file.png file.bb

to create the bounding box file file.bb for file.png.
Do not use the ebb program coming with some LaTeX distributions in conjunction with bmeps. Bmeps and ebb use different formulas to calculate the BoundingBox:

  • bmeps: 1 PNG pixel = 1 EPS point.
    72 PNG pixels are used to fill one inch.
  • ebb: 1 PNG pixel = 72/150 EPS points.
    150 PNG pixels are used to fill one inch.
Should I use the resolution chunk?

If you convert a bitmap image to EPS or PDF for use with LaTex or pdfLaTeX there are two ways to specify the size of the image on the page:

  1. You add a resolution chunk to the bitmap image and use the "-o u.r.c=y" option when running bmeps. The *.tex file contains the includegraphics command 
    \includegraphics{image}
    without the optional width argument. The image size is given by the %%BoundingBox or /MediaBox of the EPS or PDF file.
  2. You do not use "-o u.r.c=y" and skip the resolution chunk from the bitmap image file. The includegraphics command 
    \includegraphics[width=8cm]{image}
    contains information about the image size on the page you want. LaTex/pdfLaTeX uses this information and the %%BoundingBox or /MediaBox information to calculate correct scale factors.

I prefer version 2 for two reasons:

  • The size of the graphics can be changed easily in the *.tex source if necessary, no dealing with graphics programs is necessary.
  • Limitations of file formats and computer mathematics.
    The image file formats use different resolution units (dpi: dots per inch, dpm: dots per meter or dpcm: dots per centimeter) and use 16- or 32-bit integers to save the amount.
    If -- for example -- an image should be at 72 dpi and you store it as PNG the correct resolution conversion results in 2834,6457 dots per meter, this is stored as 2834 or 2835 dpm. If an application wants to show the file, it converts this value back to 71,9836 or 72,009 dpi because how should it know whether the 2834 dpm in the file mean 2834,0000 or 2834,6457 or 2834,9876 or anything else?
    If the same image is saved as TIFF or JPEG file with a resolution in dpcm the value 28,346457 is stored as 28 dpcm. Calculation backward to dpi results in 71,12 dpi.
    When using resolution information from the input image bmeps attempts to guess whether a resolution might intend 72 dpi to avoid unnecessary scaling. The delta values are as follows:
     
    JPEG files, resolution in dots per centimeter: 1.67 dpi
    PNG file, resolution in dots per meter: 0.0165 dpi
    PNG file, resolution in dots per centimeter: 1,67 dpi
    TIFF file, resolution in dots per centimeter: 1,67 dpi
    all file types/resolution units not listed above: 0.00001 dpi

     
    Do not send bug reports about this, please. This is intended.
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.tardis.ed.ac.uk/~ajcd/psutils/).
The ps2pdf script is contained in the Gostscript distributions. (http://www.cs.wisc.edu/~ghost)

Which options are recognized by bmeps?

See the Usage page for 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 <configuration-name> ...

where <configuration-name> is the same as the ``-l'' argument to the bmeps program (a configuration name, configuration entry overwrites optionally appended separated by comma).
Examples:

  • PS level 1 printer: 
    dvips -I eps1 ...
  • PS level 2 grayscale printer
    dvips -I eps2,color=no ...
  • PS level 2 color printer
    dvips -I eps2 ...
How can I configure default settings?

Both bmeps and the modified dvips retrieve default settings from the EPSOUTPUT environment variable before processing command line options.
This variable can be set in your login scripts, i.e.

setenv EPSOUTPUT eps2,color=no

in .cshrc or

EPSOUTPUT="eps2,color=no"
export EPSOUTPUT

in .profile or

set EPSOUTPUT="eps2,color=no"

in AUTOEXEC.BAT.

Is there a template to see how things work?

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}
This is a test for graphics inclusion.
\begin{figure}
{\centering
\includegraphics[width=\linewidth]{arch5.jpg}
\caption{Delicate Arch}
}
\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, may bee you need other packages and options.
The DeclareGraphicsRule is used only when not running pdftex/pdflatex/.

Using bmeps with pdfLaTeX

Can I use PDF images created by bmeps containing alpha transparency with pdfLaTeX?

Yes, you can.
Add a line

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

to the LaTeX source preamble (suggested by J. Quirk in the pdftex mailing list).
If bmeps transfers alpha channels from PNG or TIFF to PDF a notification is printed to remind you to use that line in the preamble.

How can I get rid of the "At least one alpha channel..." message?

The message

At least one alpha channel was converted to PDF.
  When referencing PDFs containing alpha data from your *.tex sources, you should use
  \ifpdf\pdfpageattr{/Group <</S /Transparency /I true /CS /DeviceRGB>>}\fi
  in the preamble.

or the german version

Ein Alpha-Kanal wurde in eine PDF-Ausgabe übertragen.
  Um PDFs mit Alpha-Kanal mit pdfLaTeX zu verwenden, sollten Sie
  \ifpdf\pdfpageattr{/Group <</S /Transparency /I true /CS /DeviceRGB>>}\fi
  in der Präambel der LaTeX-Quelle verwenden.

is printed if bmeps converts PNG or TIFF file containing alpha channel data to PDF, transferring the alpha channel.
To turn this message off, either use the -A command line argument or set the preference "/pdf/suppress-alpha-info" to "true".
On Unix/Linux edit $HOME/.defaults/all and add a section

[bmeps]
/pdf/suppress-alpha-info=true

On Windows go to the registry key (create the key if it does not exist) HKCU\Software\DkApp\bmeps and add an entry

"*:/pdf/suppress-alpha-info"=(REG_SZ)"true"

Instead of the asterisk ("*") you can use the computer name.
Alternatively run

bmeps -c -A

to set -A as a permanent option.

Mkpdfsls FAQ

What's the purpose of this script?

The mkpdfsls.pl script can be used to create a slide show, i.e. for images from your digital camera.

Which other software is required to run this script?
  • Perl.
  • The pdftk program.
  • A LaTeX distribution.
  • The beamer class for LaTeX.
  • The Image::ExifTool and DKrause::LaTeXEncoder Perl modules are needed if you want to use ``Comment'' EXIF tags from JPEG files as image descriptions.
Where can I obtain the Image::ExifTool and DKrause::LaTeXEncoder modules?

The Image::ExifTool module is available on CPAN.
The DKrause::LaTeXEncoder module is shipped with the dktools project set (http://sourceforge.net/projects/dktools). After unpacking the source archive you will find the module source in the perlxs subdirectory. Change into the DKrause-LaTeXEncoder directory and run:

perl Makefile.PL
make
make install

to install the module.

What must I do to create a slide show?
  • Collect all the images to use into one directory.
  • Create the project file (see below), i.e. ``holidays.mks''.
  • Run mkpdfsls.pl 
    mkpdfsls.pl holidays.mks
How do I create a project file?
  • The project file must contain at least the file names of the images to use, one per line, in the order of appearance in the resulting presentation.
  • Digital cameras typically use a file name scheme containing some constant characters at the beginning followed by a growing number.
    So the easiest way to create a project file is to run: 
    ls *.jpg | sort > holidays.mks
  • Now edit the holidays.mks file in your favorite text editor, create the section start entries ``[options]'' and ``[files]'' and add options if necessary.
  • If you want to show image comments, slide show title... you should use 
    presentation maker = beamer
    and add author and title information...
  • An example file might look like this: 
    [options]
presentation maker      =       beamer
theme                   =       Madrid
background              =       black
author                  =       John Doe
title                   =       Holidays in Scotland

[files]
scot01.jpg      =       Nice Landscape
scot02.jpg      =       Yet another landscape view
scot03.jpg      =       Holyrood palace
    If your JPEG files contain comments (stored in the ``Comment'' EXIF tag) you can use these commens instead of writing all the comments again: 
    [options]
presentation maker      =       beamer
theme                   =       Madrid
background              =       black
author                  =       John Doe
title                   =       Holidays in Scotland
use exif                =       yes

[files]
scot01.jpg
scot02.jpg
scot03.jpg
How does mkpdfsls.pl create a slide show?
  • In the first step the mkpdfsls.pl script converts each image source file into one PDF file.
  • In the second step the PDF files are combined using one of the following methods:
    • The pdftk program is used. 
      pdftk input1.pdf input2.pdf input3.pdf ... cat output slide-show.pdf
      Use the 
      presentation maker = pdftk
      option in the project file to activate this mechanism.
      The PDF file does not automatically attempt to switch to full-screen mode.
    • A *.tex file using the article document class and referencing all the image PDF files is written, pdflatex is run on this file.
      The resulting PDF output file will just show the image.
      Use the 
      presentation maker = plain
      option in the project file to activate this mechanism.
      The PDF file attempts to switch the PDF reader to full-screen mode.
    • A *.tex file using the beamer document class and referencing all the image PDF files is written, pdflatex is run on this file.
      The resulting PDF file will show the images, one per slide. Each slide additionally contains an image description, a slide show title...
      Use the 
      presentation maker = beamer
      option to activate this mechanism.
      The PDF file attempts to switch the PDF reader to full-screen mode.

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.vb - 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. I tested the macro on Office Prof. 2003, works fine. On earlier Office version (i.e. Office 97 Prof.) there were problems.
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.

Are there command line options for integration into Windows explorer?

To create context menu entries for bmeps use the ``-a'' option, create commands like

bmeps -a -lbb "%1"
Dirk Krause
Schmalkalden (Germany), 2012-03-04
http://dktools.sourceforge.net