# bmeps 2.1.5

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

## Usage

- Quick start for the impatient
- Configuration mechanism
- Configuration file location and structure
- Configuration entries
- Command line syntax

### Quick start for the impatient

To convert an image to EPS use

    bmeps -a -leps image.png

To create a bounding box use

    bmeps -a -lbb image.png

To convert an image to PDF use

    bmeps -a -lpdf image.png

### 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:

- `-l` configuration
  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.
- `-o` key`=`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.
- `-f` number
  `-f` number`-`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.