=head1	NAME

bmeps - convert PNG to EPS

=head1	SYNOPSIS

  bmeps [<options>] [ <inputfile> [<outputfile>] ]

=head1	DESCRIPTION

The bmeps package consists of a command line tool and a library
for bitmap-to-EPS conversion.

Depending on the libraries installed on your system bmeps can
convert PNG, JPEG and NetPBM files to EPS.

The EPS images are intended for use with text processing and
DTP systems (i.e. LaTeX), not for direct printing.
No attempts are made to fit pages of any paper size,
scaling and rotating is left up to the text processing software 
using the EPS images.

You can produce EPS level 1, 2 or 3. Different compression and encoding
mechanisms are available: run-length-compression (requires EPS level 2),
flate compression (requires EPS level 3) and ASCII-85-encoding (requires
EPS level 3).

Alpha channels in PNG files can be used to mix against a user specified
background colour and/or to create an image mask for EPS level 3 output
files.

=head1	OPTIONS

=over 2

=item	B<-p>I<pslevel>

Chooses EPS level I<1>, I<2> or I<3>.

=item	B<-c>   or   B<-g>

Selects coloured output (c) or enforces grayscaled (g) output.
Coloured output requires EPS level 2 or above.

=item	B<-e>I<encoding>

Enables compression and encoding mechanisms. I<encoding> is a string
consisting of key characters representing encodings to enable:

=over 4

=item	* C<8>

ASCII-85-encoding. Requires EPS level 2 or above.

=item	* C<r>

Run-length-compression. Requires EPS level 2 or above.
=back

=item	* C<f>

Flate compression. Requires EPS level 3 or above.

=back

=item	B<-s>

This option enables output of DSC comments. DSC comment output
is disabled by default, except bounding box output.

=item	B<-b>

Only generates only line containing the bounding box information.

=item	B<-d>

Switches to draft mode. In draft mode no real image conversion is
done, a simple gray rectangle is printed instead.

=item	B<-a>I<alpha-channel-options>

Specifies how to handle an alpha channel in a PNG image.
Without this option the image is mixed against a white background.
If the C<-a> option is present and EPS output level is 3 or above
an image mask is created. The I<alpha-channel-options> can be used
for a detailed setup.
This string consists of the following optional components:

=over 4

=item	B<o>   or   B<t>

specifies whether the alpha channel expresses opacity (o, default)
or transparency (t).

=item	B<m>

mix against background in addition to creating an image mask.
By default the background colour from the PNG background chunk is used.

=item	I<ddd,ddd,ddd>

provides a default background colour which is used if the PNG file
does not contain a background chunk.
The decimal numbers build up an RGB triple, i.e. 128,255,128 for
light green.

=item	B<s>

ignores a PNG background chunk and uses the user specified background
regardless whether or not the PNG file contains a background chunk.

=item	B<l>

inverts the image mask triggering level. By default only opacity=0
pixels are masked. When using the C<l> option only pixels with
full opacity are drawn, all others are masked.

=back

=head1	RETURN VALUE

On successfull completion the program returns C<0>, otherwise C<1>.

=head1	OPTIONS EXAMPLE

To convert the file S<file.png> to S<file.eps> use

  bmeps -p3 -c -erf8 file.png file.eps

EPS level 3 is used, output is coloured. The combination of
run-length-compression, flate compression and ASCII-85-encoding is
used to minimize output size.

If the document contain the EPS file must be printed on an older
EPS level 2 grayscale printer use

  bmeps -p2 -g -er8 file.png

=head1	ENVIRONMENT

Default options can be set up in the C<EPSOUTPUT> environment variable.
The variable contains a string consisting of the following
components:

=over 2	

=item	* EPS level

Use character B<1>, B<2> or B<3> to set the EPS level

=item	* Coloured or grayscaled output

Use the character B<c> for coloured output, B<g> for grayscaled output.

=item	* Compression and encoding mechanisms

Use the characters B<r>, B<f>, B<8> or combinations to enable run-length
compression (r), flate compression (f) and ASCII-85-encoding (8).

=item	* Alpha channel handling

Use the character B<a> followed by an optional alpha-options string
to set up alpha channel handling. The alpha-options string consists
of the following optional components:

=over 4

=item	* Character B<o> or B<t>

indicates whether the alpha channel
expresses opacity (default) or transparency.

=item	* Character B<l>

turns the trigger level from
"mask only opacity=0" pixels to "draw only full opacity pixels".

=item	* Character B<m>

enables mixing against a background colour in
addition to image mask creation.

=item	* A I<ddd,ddd,ddd> decimal RGB-triple

specifies a default
background colour to use if there is no background chunk in the PNG file.

=item	* Character B<s>

always uses the specified background colour
for mixing, the background chunk is ignored.

=back

=back

=head1	ENVIRONMENT EXAMPLES

In a Bourne shell use

  EPSOUTPUT=3crf8am128,255,255s
  export EPSOUTPUT

to set default options to EPS level 3, coloured output, run-length
compression, flate compression and ASCII-85-encoding, image mask
creation and mixing always against a light green background.

In a C shell use

  setenv EPSOUTPUT 2g8r

to set default options to EPS level 2, grayscaled output, run-length
compression and ASCII-85-encoding. This is suitable for most office
printers.

On the DOS prompt box use

  set EPSOUTPUT=3cf8

to set default options to EPS level 3, coloured output, flate compression
and ASCII-85-encoding. This is suitable for output which is viewed
and processed by PostScript interpreters, ie.e GhostScript.

=head1	RESTRICTIONS

Conversion maps 1 PNG pixels to a pixel of 1 PS point width.
No scaling or rotating is done by bmeps to fit output into any
paper size.
The application including the EPS file into any document is
responsible for scaling and rotating.

=head1	NOTES

=head2	bmeps and LaTeX (unmodified dvips)

The bmeps program was originally created to insert screenshots into
LaTeX documents.
To include PNG files the C<graphicx> package is needed.
In the preamble write a graphics rule

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

telling LaTeX that PNG files (having file name suffix .png) can be
converted to EPS. If LaTeX finds an instruction to include a *.png
file it reads a *.bb file (same file name but .bb suffix) to read
a bounding box information to calculate the aspect ration
(width/height relation).
This bounding box file can be created by using the B<-b> option.
If you have a PNG file S<image.png> run

  bmeps -b image.png image.bb

In the LaTeX document include the image using a

  \includegraphics[width=\linewidth]{image.png}

line.
If dvips processes the dvi file and needs to include the PNG file
it runs C<bmeps image.png>. If only an input file name is specified
on the bmeps command line output goes to the standard output
which is processed by dvips here and transferred to the final print
job.

Although one could specify conversion options in the C<\DeclareGraphisRule>
line this is not recommended.
When including images in LaTeX documents it is recommended to use
the EPSOUTPUT environment variable to set up the conversion.

=head2	bmeps and LaTeX (modified dvips)

The bmeps package also contains suggestions how to modify dvips.
To check whether or not your dvips is modified, run

  dvips --help

If the output contains "I s image options" dvips can handle PNG images
itself and does not need to run bmeps as an external process for each
image.
In this case the graphics rule declaration looks like this:

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

Conversion options can be set up either in the EPSOUTPUT variable or on
the command line, i.e.

  dvips -I 2gr8 ...

=head1	SEE ALSO

There is more documentation available in HTML and PDF format.
Typically this documentation is installed "near" the bmeps binary
in a directory C<../docu>.

=head1	AUTHOR

Dirk Krause

=head1	COPYRIGHT AND LICENSE

Copyright 2001-2003 by Dirk Krause

This is free software; you can redistribute it and/or modify it under the
terms of the GNU Library General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.   This software is distributed in the hope that
it will be useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.    See the
GNU Library General Public License for more details.   You should have
received a copy of the GNU Library General Public License along with this
software; if not, write to the
Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.

=head1	LAST MODIFICATION

2003/11/11

