GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
bitmap2pp(1) DK tools and libraries bitmap2pp(1)

bitmap2pp - Bitmap to PDF/PS converter

bitmap2pp -ldriver[.mode][,name=value...] options file(s)

The program converts bitmap image files from PNG, JPEG, TIFF, and NetPBM to PDF and PS/EPS. In this text "bitmap image" refers to bitmap, graymap and pixmap images.

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.

-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 are used to specify configuration details.

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:
chunk
Obtain resolution information from input image file, if available. This is the default. If there is no resolution information in the input file, use 1px1pt.
1px1pt
Use 72 dpi for resolution in both x and y direction. Ignore resolution data in input image file if present. Each pixel from input file will use a 1 PS point square in output.
number
The specified floating point number is used as resolution in dpi for both x and y direction.
number:number
The first number specifies the resolution in x direction, the second one specifies the resolution in y direction. I recommend to use number and number:number only.

The "chunk" and "1px1pt" variants are only available for backward compatibility. Chunk is the default, instead of 1px1pt you should better use "i-res=on".

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.

PNG/TIFF/NetPBM files can contain an alpha channel. A pixels alpha value expresses opacity in the range 0=transparent to 1=fully opaque. An alpha channel found in the input image file is transferred into an SMask object in PDF output. For PS/EPS output we have to calculate the color of each pixel, there are two choices:
  • 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.

Flate compression is used for PDF output and PS level 3 output.

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.

If the number of bits per component can be reduced for all components of all pixels without quality loss, the smaller bit depth is used in output.

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.

The following variables containing integer values are used in the formulas below:

 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
    

If image resolution information is available the real image dimensions in PS points are calculated by multiplication of width/height in pixels by factor 72, division by x/y resolution and rounding upwards to the next integer value. The source of the image resolution is either the input image file if it contains resolution data (resolution=chunk, this is the default) or a resolution specified by the user (resolution=number or resolution=number:number).

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.

0 on success, all other values indicate errors.

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
    

  • 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?
On the command line
Use "-lps,level=2" instead of "-lps".
In a dk4gra.conf file
Create a file dk4gra.conf in one of the following directories
${datadir}/dk4app-site to set defaults for all users.
${sysconfdir}/dk4app-site to set defaults for all users.
${HOME}/.dk4app to set defaults for the current user.

containing the following lines:

  [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.

On the command line
Use "-lps,level=2,lzw" instead of "-lps,level=2".
In a dk4gra.conf file
Create a file dk4gra.conf containing the following lines:

  [ps]
  level=2
  lzw=on
    

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:

  • ${datadir}/dk4app/dk4gra.conf
  • ${sysconfdir}/dk4app/dk4gra.conf
  • ${datadir}/dk4app-site/dk4gra.conf
  • ${sysconfdir}/dk4app-site/dk4gra.conf
  • ${datadir}/dktools/dk4gra.conf
  • ${sysconfdir}/dktools/dk4gra.conf
  • ${datadir}/dktools-site/dk4gra.conf
  • ${sysconfdir}/dktools-site/dk4gra.conf
  • ${datadir}/bitmap2pp/dk4gra.conf
  • ${sysconfdir}/bitmap2pp/dk4gra.conf
  • ${datadir}/bitmap2pp-site/dk4gra.conf
  • ${sysconfdir}/bitmap2pp-site/dk4gra.conf
  • ${HOME}/.dk4app/dk4gra.conf
  • ${HOME}/.dk4app/dktools/dk4gra.conf
  • ${HOME}/.dk4app/bitmap2pp/dk4gra.conf
  • ./dk4gra.conf

File name size is restricted to MAXPATHLEN respectively _PATH_MAX on your system. The full path names of all files used must fit into this length.

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.

Dirk Krause

The first version of this program was named bmeps.

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.

The ``DK tools and libraries'' project (abbreviated: ``dktools'') uses a BSD style license, see dktools-legal(1) for details.

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.
2022-02-17 4.32.0

Search for    or go to Top of page |  Section 1 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.