NAME

SYNOPSIS

DESCRIPTION

For each input file specified on the command line the program creates a corresponding output file with file name suffix ".pdf", ".eps", ".ps", or ".bb".

If a directory name is specified on the command line, bitmap2pp traverses the directory and converts all files suitable as bitmap2pp input. In the special make-mode bitmap2pp converts only those files for which there is no up-to-date output file yet.

The driver choice indicates the file type to produce:

pdf

Portable document format (PDF).

eps

Encapsulated PostScript (EPS), image for inclusion in documents.

ps

Print job file for printing on PostScript printers.

bb

Bounding box file, contains image dimensions only, no image contents. LaTeX needs such files sometimes to know how much space to reserve for an image.

The output mode indicates the intended purpose of the output:

object

Object, a file embedded into a graphics or text document by a drawing software or text typesetting software.

image

Image for stand-alone viewing and processing.

document

The image is fitted to a specified paper size or usable area on paper for printing.

OPTIONS

-l driver[.mode][,key=value...]

--language=driver[.mode][,key=value...]

specifies output driver and output mode. The optional key=value pairs can be used for further configuration. See section "key=value pairs" below.

-m

--make

turns on "make operating" for directory processing. When processing directories, bitmap2pp in normal operating processes each file it can process. In make operating it processes only those files for which there is no up-to-date output file yet.

-R

--reset

resets the program to built-in default settings, the dk4gra.conf configuration files are ignored.

--help

shows a short help text.

--manual

shows a detailed help text.

--version

shows the version number.

--license

shows the license conditions of both bitmap2pp and the used libraries.

KEY=VALUE PAIRS

For boolean settings it is sufficient to write the name to activate the option. As an example "-lps.document,duplex" has the same effect as "-lps.document,duplex=true". Use "on", "true", or "yes" to activate boolean settings. Use "off", "false", or "no" for deactivation.

The following settings can be made:

level=integer

PS language level when producing PS output, 2 or 3. Default: 3.

dsc=boolean

Write DSC comments (document structuring convention) to PS/EPS output files. Default: off

lzw=boolean

Allow the use of LZW compression in PS level 2 output. Default: off

color=boolean

Allow colored output. Default: on. Deactivating this option results in grayscaled output.

rgb-to-gray=string

Method to convert RGB data to grayscale values. Default: bt601. See section "Color space conversion" below.

rgb-to-cmyk=string

Method to convert RGB data to CMYK, one from "non-standard" or "standard". Default: non-standard. The bitmap2pp program does not convert from RGB to CMYK and there are no plans to do so. The option is mentioned here for completeness as the used libdk4gra library supports this configuration option.

alpha=string

Method for alpha channel use, either "mix" or "foreground". Default: mix. See section "Alpha channel" below.

bg=integer:integer:integer[:boolean]

Default background color. The numbers are RGB values in the range 0...255. Default: 255:255:255. Normally the color specified here is only used if the input image does not contain background color information. The optional boolean flag decides about enforcing the background color. Enforcing means the background color is used even if there is background color information in the input image file. I recommend to use the "force-bg" option instead of specifying the boolean flag here.

force-bg=boolean

Enforcing the background color can be set up differently from specifying the background color. Default: off.

interpolation=boolean

Set interpolation flag in output. If this flag is set, PDF/PS rendering programs are allowed to attempt to improve image representation. Default: on.

dct=boolean

Allow direct re-use of DCT encoded data from JPEG input files. This avoids decoding and encoding and results in faster processing and smaller output files. Default: on.

dct-interpolation=boolean

Set image interpolation flag when directly re-using DCT encoded data from JPEG files too. Default: off.

a-bpc=boolean

Analyze bits per component. Reduce number of bits per component if reduction if possible without quality loss. Default: on.

a-color=boolean

Analyze use of colors, switch output color space to grayscaled if all pixels are gray. Default: on.

a-alpha=boolean

Analyze alpha channel use, avoid writing an SMask object to PDF output if all pixels are fully opaque. Default: on.

paper=string

Paper size for documents. The paper size must be defined in a dk3paper.conf or dk4paper.conf file. Default: a4.

duplex=boolean

Prepare PS output for duplex printing (print on front side and back side of paper sheet, binding on the left side like a book). Default: on.

tumble=boolean

Prepare PS output for duplex+tumble printing (print on front side and back side of paper sheet, binding on top side like a calendar). Default: off.

resolution=choice

How to use resolution and calculate image size, one from:

i-res=boolean

Ignore resolution information in input image file. Use 72 dpi, so the image width and height in PS point is equal to the number of pixels in width and height of the input image. The result is the same as "resolution=1px1pt". Default: off.

i-aspect=boolean

Ignore aspect ratio of input image. When creating a document the entire available (printable) area on paper sheet is used for the image. A distortion due to different x and y scale factors is accepted. Default : off.

rotate=boolean

Allow image rotation by 90 degree if the rotated image fits better into the usable area. Default: off.

rsize=boolean

Restrict object or image size when creating EPS or PDF images or objects from bitmap images. The LaTeX typesetting system refuses to process objects with dimensions larger than 2^{30} sp. This corresponds to slightly more than 16322bp (big points, 72bp=1inch). If this option is enabled, the image resolution is increased to result in width and height of maximally 16322bp. This option is enabled by default when creating EPS/PDF images or objects, disabled when creating documents.

rsdct=boolean

Allow direct re-use of DCT encoded data from JPEG files even if the image is scaled down due to size restriction. Default: on.

ALPHA CHANNEL

• Mixing the foreground color as retrieved from input file against a background color considering opaqueness from alpha channel. This is the default.
• Simply use the foreground information found in input image file. Use "alpha=foreground" to configure this.

A background color information (background color chunk) in the input image file is used by default, if present.

For input images without background color information you can use the "bg=..." option to define a default background color. Using "force-bg=on" you can configure to use the bg=... color even if the input image file contains background color information.

When creating a PDF document, each page is completely filled with white color before applying any image.

When creating a PDF image for an image containing transparency, the image area is filled with background color before applying the image.

COMPRESSION AND ENCODING

Run length compression with separated color channels is used for PS level 2 output if the number of bytes per color channel per row does not exceed 16384. For images with larger rows no compression is used. Alternatively you can enable LZW compression.

For separated color channels the data stream contains all red values for a row first, all green values next, all blue values finally. Without separated color channels a horizontal red line would be represented by the byte values: 255 0 0 255 0 0 255 0 0 255 0 0 255 0 0 ...

Run length compression would not be possible. With separated color channels the red channels contains: 255 255 255 255 255 ...

The green and blue channels contain: 0 0 0 0 0 ...

So run length compression can be applied to colored lines.

The compression result is used directly without any further encoding for PDF output. For PS/EPS output ASCII-85 encoding is applied to produce clean 7 bit text.

IMAGE ANALYSIS

If the input image uses RGB, RGB+alpha or CMYK color space but all pixels are gray, bitmap2pp produces grayscaled output.

If the input image contains an alpha channel but alpha data indicates full opacity for all pixels, no SMask object is written to PDF output.

COLOR SPACE CONVERSION

 MAX: Maximum value for a given number of bits per
      component (i.e. 15 for 4 bits, 255 for 8 bits)
 R:   Red component in range 0 ... MAX
 G:   Green component in range 0 ... MAX
 B:   Blue component in range 0 ... MAX
 E:   Grayscale value in range 0 ... MAX

Several methods can be used to convert RGB data to gray:

bt601

Keep luminance:

        E = (299 * R + 587 * G + 114 * B) / 1000
    

luminance

Keep luminance, use shorter coefficients:

        E = (30 * R + 59 * G + 11 * B) / 100
    

fast

Fast calculation without division operations:

        E = (77 * R + 151 * G + 28 * B) >> 8
    

fastest

Yet faster and more inaccurate calculation without multiplication and division (<< and >> are bit shifting operations to left and right):

        E = ((R << 1) + (G << 2) + G + B) >> 3
    

bt709

Keep luminance, use other coefficients:

        E = (2126 * R + 7152 * G + 722 * B) / 1000
    

average

Average of red, green, blue:

        E = (R + G + B) / 3
    

desaturation

Desaturation results in an image with less contrast:

        E = (maximum{R,G,B} + minimum{R,G,B}) / 2
    

min

Minimum decomposition uses the minimum of R, G, B:

        E = minimum{R,G,B}
    

median

Median decomposition uses the median value of R, G, B:

        E = median{R,G,B}
    

max

Maximum decomposition uses the maximum of R, G, B:

        E = maximum{R,G,B}
    

red

Just use the red component:

        E = R
    

green

Just use the green component:

        E = G
    

blue

Just use the blue component:

        E = B
    

IMAGE SIZE, RESOLUTION AND ROTATION

If the input image file does not contain resolution data or the user decides to ignore resolution data (i-res=on), a resolution of 72 dpi is used. The output image width/height in PS points is equal to the input image width/height in number of pixels.

Some input images - i.e. TIFF files generated by a fax gateway - contain different resolutions for x and y direction. For such images ignoring the resolution results in image distorsion.

There are two choices to fit an image into a usable/printable area of a page or paper sheet:

• Keep the aspect ratio (default), probably leaving parts of the available area unused.
• Ignore the aspect ratio (i-aspect=on) and fill the area completely accepting image distorsion.

For some image/paper combinations - i.e. the image is more wide than high but the paper is more high than wide - rotating the image by 90 degree allows better fitting to the available area. The rotate=on option allows such rotations.

EXIT STATUS

EXAMPLES

Create PDF object for use with pdfLaTeX from screenshot.png file:

  bitmap2pp -l pdf screenshot.png
    

Create EPS object screenshot.eps for use with LaTeX/dvips:

  bitmap2pp -l eps screenshot.png
    

Create PDF file fax.pdf for printing from fax.tif file:

  bitmap2pp -l pdf.document,paper=A4,duplex fax.tif
    

Create PS file fax.ps for printing, use language level 2:

  bitmap2pp -l ps.document,level=2,paper=A4,duplex fax.tif
    

Create standalone image file file.pdf from file.png file:

  bitmap2pp -l pdf.image file.png
    

Create standalone file file.ps from file.png file:

  bitmap2pp -l ps.image file.png
    

FAQ

• Do I need to create a dk4gra.conf file?

  The dk4gra.conf configuration file can be used, but normally there is no need to do so. I hope I selected useful defaults for the bitmap2pp program. One reason to create a dk4gra.conf file is to support PS printers handling PS language level 2 only.

• How do I switch PS language level to 2?

  [ps]
  level=2

•

How do I enable LZW compression for PS level 2 output?

Note: The LZW algorithm was patent protected for a long time. The patent in the USA expired in 2003, the corresponding patent in Germany expired in 2004. I do not know the situation in all countries over the world, so you should check the situation in your country yourself. Activate LZW only if you are allowed to use it and if you really need it.

FILES

dk3paper.conf / dk4paper.conf

are the configuration files to define paper sizes. If paper=... is used, the paper size must be defined in one of these files.

dk4gra.conf

is the configuration file for graphics output from the DK tools and libraries project.

Cumulative processing is used. Settings made in a file processed earlier may be overwritten in files processed later. The ${datadir}/dk4app, ${sysconfdir}/dk4app, ${datadir}/dktools, ${sysconfdir}/dktools, ${datadir}/bitmap2pp directories are managed by the package management, you should not create or modify files here. Files in these directories may be updated or deleted during package updates. Use ${datadir}/dk4app-site, ${sysconfdir}/dk4app-site, ${datadir}/dktools-site, ${sysconfdir}/dktools-site, ${datadir}/bitmap2pp-site, ${sysconfdir}/bitmap2pp-site, ${HOME}/.dk4app, ${HOME}/.dk4app/dktools, or ${HOME}/.dk4app/bitmap2pp for customized dk4gra.conf files.

On start the bitmap2pp program checks for the file in the following locations in the specified order:

RESTRICTIONS

The program uses the TIFFReadRGBAImage() function from the libtiff library to read TIFF images. The input file must meet the following conditions:

• The file must be compliant to the "TIFF baseline v6.0 standard".
• The number of bits per component must be 8 or less.
• The frames must not be too large, the system must be able to allocate the 4*w*h bytes needed for image date in one piece.

TIFF refers to a group of different compression and encoding mechanisms. A TIFF file is a sequence of data chunks, each data chunk contains a tag (chunk type identifier). A lot of tags is defined in standards, i.e. the "TIFF baseline v6.0 standard". Some software vendors add vendor-specific or non-standard tags when writing TIFF files. So when processing TIFF files in bitmap2pp, you should not be surprised to see warnings or error messages about unknown TIFF tags. Neither bitmap2pp nor the tifflib library are to blame for this, it's the responsibility of the people adding the non-standard tags. Sometimes bitmap2pp can read the image despite of the warnings/errors.

If you create bitmaps you want to process with bitmap2pp, you should create PNG images instead of TIFF images if you have the choice.

AUTHORS

HISTORY

The program was rewritten completely for version 4.12.0, including the used libraries for reading bitmap images and producing graphics output. The program was renamed to bmpp.

For version 4.33.0 the program was renamed to bitmap2pp because packaging guidelines for some Linux distributions (i.e. Debian GNU/Linux) require a minimum name length of 5 characters.

COPYRIGHT AND LICENSE

SEE ALSO

pnmtops(1)

The pnmtops program from the NetPBM project - see <http://netpbm.sourceforge.net> - converts NetPBM input files to PS and EPS.

convert(1)

The convert program from the ImageMagick project can also convert to EPS and PDF.

dk3paper.conf(5)

How to define paper sizes.

dk4gra.conf(5)

Syntax of dk4gra.conf files.

<http://sourceforge.net/p/dktools/wiki/Home/>

Project homepage.