bmeps - convert PNG/JPEG/NetPBM to EPS

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

Overview / Installation / Usage / FAQ / Change Log / Other Projects

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

| Command line options
|  | Program invokation
|  | Bounding box creation
|  | Image conversion options
|  |  | Usual conversion options
|  |  | Alpha channel handling
|  |  | Obtaining resolution from PNG pHYs chunk
|  | Draft option
|  | Option examples
| EPSOUTPUT environment variable
|  | Contents
|  | Examples
| How to use bitmap graphics in LaTeX
|  | Declaring the file type
|  |  | Unmodified dvips
|  |  | Modified dvips
|  | Run dvips
|  | LaTeX examples
|  |  | Example sources
|  |  | Example outputs

### Command line options

#### Program invokation

The program is invoked by

      bmeps [<options>] [ <input-file> [<output-file>] ]

If no output-file is specified output goes to standard output. If the input-file argument is omitted too, input is read from standard input, the program runs as a filter. In this case it is necessary to use the `-t` option to specify the file type (see below).

#### Bounding box creation

The `-b` option can be used to generate a bounding box file as it is needed by LaTeX, i.e.

      bmeps -b image.png image.bb

reads a PNG file image.png and writes a bounding box file image.bb.

#### Image conversion options

##### Usual conversion options

- EPS level

        -p <eps-level>

  The eps-level can be either `1`, `2` or `3`. To establish EPS level 3, run

        bmeps -p 3 ...

- Coloured or greyscaled output
  The `-c` option enables coloured output, `-g` enforces greyscaled output.
- Compression and encoding mechanisms

        -e <encoding>

  selects the encoding mechanisms to use. The encoding argument is a string consisting of key characters:
  - `r` for run-length compression
  - `8` for ASCII-85-encoding
  - `f` for flate compression
- Showpage operator

        -o

  enables usage of the showpage operator at the end of the file. This operator is turned off by default for version 1.0.9 and above.
- PostScript memory usage

        -u

  creates a separated dictionary for /pstr and /inputf. The dictionary is removed from the dictionary stack at the end of the EPS file.

        -r

  forces a garbage collection to reclaim memory ("1 vmreclaim").
- DSC comments
  By default output of DSC comments is disabled (except BoundingBox). To enable output of DSC comments use the `-s` option.
- File type
  By default the bmeps program tries to find the file type by examining the file name.
  If bmeps is running as a filter or if you have "unusual" file names the file type must be specified by

        -t <file-type>

  where file-type can be "png", "jpg" or "pnm".
- Verbose mode
  If bmeps encounters an error in an input file an error message is written as PostScript comment to the output.
  If verbose mode is enabled using the

        -V

  option the error message is also written to the standard error stream.

##### Alpha channel handling

- Alpha channel handling can be set up using

        -a <alpha-options>

  If this argument is present an alpha channel in the PNG file is converted into an EPS level 3 image mask. The alpha-options argument is a string consisting of the following components:
  - Transparency / Opacity switch
    By default the alpha channel data is assumed to be opacity (`o`). The character `t` switches to transparency.
  - Trigger level for image mask
    By default only pixels having opacity=0 are masked out. Character `l` toggles the trigger level, only pixels having full opacity are drawn, all others are masked out.
  - Mixing in addition to image mask
    The character `m` turns on mixing in addition to image mask creation. If the PNG file contains a background color chunk, mixing is done against the background colour specified there. Otherwise a user specified background colour is used.
  - Default background colour
    An RGB-triple (i.e. `128,255,128` for light green) can be used to specify a default colour for mixing. Note: This colour is used only if the PNG file does not contain a PNG background channel or if the `s` key is specified.
  - Always use specified background
    If you want to ignore the PNG background chunk use the `s`.

#### Obtaining resolution from PNG pHYs chunk

If you want to use the same resolution in the EPS output file as specified in the PNG files pHYs chunk (if there is one), use the `-q` option.
This feature was implemented on one user's request for special purposes and is not yet well-tested. Normally you should not use it as scaling the image is left up to LaTeX or a DTP application of your choice. But the feature might be usefull to create EPS images for standalone viewing.
This feature is new and not yet well-tested.

#### Draft option

Using the `-d` option runs the program in draft mode, no image conversion is done, a grey rectangle is printed instead.

#### Options examples

      bmeps -p 2 -g -e r8 image.png image.eps

converts file image.png to image.eps. EPS level 2 is used, greyscaled output is enforced. Run-length-compression and ASCII-85-encoding are used to produce the smallest possible output file.
This option set is a typical example when printing on a PS-level-2 printer.

      bmeps -p3 -c -e8rf -am128,255,255s image.png image.eps

converts image.png to image.eps. EPS level 3 is used, output is coloured. A combination of all compression/encoding mechanisms available in EPS level 3 is used.
If image.png contains an alpha channel, this is used to produce an EPS image mask. In addition to building an image mask the colours are mixed against a light green background, a PNG background colour chunk is ignored.

### EPSOUTPUT environment variable

#### Contents

To establish default settings one can use the `EPSOUTPUT` environment variable.
The value of this variable is a string consisting of the following:

- Verbose mode: The character `V` enables verbose mode.
- EPS level: One of the characters `1`, `2` or `3`.
- Coloured or greyscaled output: One of the characters `c` or `g`.
- Compression/encoding mechanisms: A combination of the characters `r`) (for run-length-compression), `f` (for flate compression) and/or `8` for ASCII-85-encoding.
- Operator showpage: The `h` character enables use of the "showpage" operator.
- PostScript memory management: The `u` character creates a separated dictionary, the `v` character enables usage of "1 vmreclaim".
- DSC comments: Character `x` enables DSC comment output.
- Alpha channel handling: Character `a` enables image mask creation based on alpha channel data. This character may be immediately followed by an alpha channel configuration substring consisting of the following:
  - Character `o` or `t` to specify whether the alpha channel expresses opacity or transparency.
  - Character `l` to toggle the trigger level from the default (mask opacity=0 pixels only) to the alternate level (draw opacity=full pixels only).
  - Character `m` to do mixing against a background colour.
  - Decimal RGB triple to specify a default background colour, used if no PNG background chunk available or `s` given.
  - Character `s` to always use the user specified background colour.
- Exact resolution: Character `e` sets up bmeps to use the same resolution for EPS output as was specified in the PNG files pHYs chunk (if there is any). Not recommended when producing EPS for use with LaTeX or DTP applications.
- Draft mode: Character `d` sets up draft mode.

#### Examples how to use the EPSOUTPUT environment variable

      EPSOUTPUT=2g8r
      export EPSOUTPUT

can be used in a Bourne-Shell or derivate to set up EPS level 2, greyscaled output, run-length compression and ASCII-85-encoding.

      setenv EPSOUTPUT 3c8rfa128,255,128s

can be used in a C-Shell or derivate to set up for EPS level 3, coloured output, maximum compression by use of run-length compression, flate compression and ASCII-85-encoding.
If the PNG file contains an alpha channel an image mask is created, additionally each pixels colour is mixed against a light green background. Background chunks in the PNG file are ignored.

      set EPSOUTPUT=d

can be used on the DOS-prompt to set draft mode.

### How to use bitmap graphics in LaTeX

#### Declaring the file type

##### Unmodified dvips, runs bmeps if necessary

By default LaTeX does not accept PNG/JPEG/NetPBM graphics, we must declare graphics rules for these file types.
In the document preamble write

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

This tells LaTeX that files having suffix .png can be converted to EPS. The bounding box for such a file is specified in a file having the same name but suffix .bb.
When dvips comes to a place to insert an image, it runs the bmeps program for the specified .png file. No output file name is specified in the command so bmeps writes to standard output which is read by dvips and transferred into the final output .ps file.

##### Modified dvips, internal conversion

If you have a modified dvips available, the graphics rule looks like

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

There is no need for dvips to run an external conversion program.

#### Running dvips

Before running dvips you should set the EPSOUTPUT variable.
If you have a modified dvips available, you can also specify conversion options using the `-I` option, i.e.

      dvips -I 2g8r ...

#### LaTeX examples

##### Example sources

The `EXAMPLES` subdirectory contains Postscript files derived from the same example.tex file using different options.
The image stefan_255_rgba.png was obtained from the "Miscallenous Transparent PNGs Using Image Tags" page on the libpng home page.

Image |  | LaTeX source
--- | --- | ---
Some levels of gray in this image are produced by specifying a black foreground, a white background and an alpha channel value for mixing. |  |
    \documentclass[titlepage,12pt]{article}
    \usepackage{a4}
    \usepackage{geometry}
    \usepackage[T1]{fontenc}
    \usepackage{times}
    \usepackage[latin1]{inputenc}
    \parindent0cm
    \usepackage{longtable}
    \usepackage{varioref}
    \usepackage{makeidx}
    \usepackage{graphicx}
    \usepackage{hyperref}
    \usepackage[dvips]{color}
    %
    % The pagecolor instruction in the line below was used
    % to produce the bg...ps files.
    %
    % \pagecolor{cyan}

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

    \geometry{body={17cm,22cm},top=1cm,left=2.5cm}
    \makeindex
    \begin{document}
    \begin{sloppy}
    \section{Example}
    The options \texttt{1g} were used to create this file.
    \begin{figure}
    \begin{center}
    \caption{Bird}
    \includegraphics[width=4cm]{stefan_255_rgba.png}
    \end{center}
    \end{figure}
    \end{sloppy}
    \end{document}

##### Example outputs

- The 1g.ps file (20112 bytes) was created by

        latex example
        dvips -I 1g example
        mv examples.ps 1g.ps

  We use PS level 1 and convert colors to gray.
- The 2g8r.ps file (34265 bytes) was produced using the options `2g8r`.
  The image is converted to gray scale, PS level 2 is used so we are free to use run-length-compression and ASCII85-encoding.
- The 2c8r.ps file (56158 bytes) is the colored version.
- The 3c8rf.ps file (34773 bytes) was produced using the options `3c8rf`.
  Postscript level 3 allows to use flate compression, so we combine run-length-compression, flate compression and ASCII85-encoding here to obtain the smallest possible output file.

Now we show how to deal with the alpha channel.
The line

    \pagecolor{cyan}

in the TeX source file was activated to establish a page background color.

- The bg3c8rf.ps file was produced using `3c8rf`.
  The alpha channel in the PNG image is unused.
- The bg3c8rfa.ps file was produced using `3c8rfa`.
  The alpha channel is converted into an image mask.
  All pixels having opacity > 0 are drawn in the color specified by the PNG file, pixels with 0 opacity are skipped.
  The alpha channel is obtained separately and used only for image mask creation, not to mix pixel colors. This produces black regions if alpha channel values are used to mix black foreground and white background to gray.
- The bg3c8rfam.ps file was produced using `3c8rfam`.
  Each pixel color is calculated using foreground color, opacity and background color. Foreground color and opacity are specified in the PNG file. If the PNG file contains a background color chunk this color is used, otherwise the background color is white.
  Here we have the gray ranges as expected.
- The bg3c8rfams0_255_255.ps file was produced using `3c8rfams0,255,255`. Each pixel color is calculated using foreground color and opacity from the PNG file and the specified background color cyan (RGB=0,255,255).

To create a draft file using placeholders for bitmap images only one can use the `d` option, a result is shown in d.ps.