Usage |
PDF manual "bmeps.pdf" available |
Command line options
Program invokation
The program is invoked by
bmeps [<options>] [ <input-file> [<output-file>] ]If no
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.bbreads a PNG file
Image conversion options
Usual conversion options
- EPS level
-p <eps-level>
Theeps-level can be either 1, 2 or 3. To establish EPS level 3, runbmeps -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. Theencoding 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>
wherefile-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. Thealpha-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.
- Transparency / Opacity switch
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.epsconverts 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.epsconverts
If
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 EPSOUTPUTcan 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,128scan 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=dcan 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.
