dktools - Dirk Krauses tools Wiki

Drawing, graphics conversion, software development, administration.

Brought to you by: kraused

bitmap2pp manual

Authors:

bitmap2pp — Convert PNG / JPEG / TIFF / NetPBM → PDF / EPS

For the impatient: See the Examples section below.

Synopsis

bitmap2pp -ldriver.mode,key=value… options files

Description

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.

If bitmap2pp is invoked without specifying a file name, the program runs as filter reading a NetPBM image from standard input and writing output to standard output.

The driver choice indicates the file type to produce:

Driver	Output
pdf	Portable document format (PDF).
eps	Encapsulated PostScript (EPS), image for inclusion in documents.
ps	Print job file for use on PostScript printers.
bb	Bounding box file, contains dimensions only.

The output mode indicates the intended purpose of the output:

Mode	Purpose
object	Object, a file embedded into a graphics or text document by a drawing software or text typesetting software. Only the first frame from the input image file is used. For PDF output: An alpha channel found in the input image file is converted to an SMask object. For other output: The alpha channel data is used to mix foreground colour against background colour.
image	Image for stand-alone viewing and processing. Only the first frame from the input image file is used. For PDF output: An alpha channel found in the input image file is converted to an SMask object. Before applying the image the area used by the image is filled with the specified background. For other output: The alpha channel data is used to mix foreground colour against background colour.
document	The image is fitted to a specified paper size or usable area on paper for printing. All frames from the input image file are used, each frame results in one output page. For PDF output: An alpha channel found in the input image file is converted to an SMask object. Before applying the image the area used by the image is filled with the specified background. For other output: The alpha channel data is used to mix foreground colour against background colour.

You can append key=value pairs for detailed configuration, but this is normally not necessary.

Options

Option	Purpose
-ldriver --language=driver	Output driver, optionally mode, optionally key=value pairs for detailed configuration. See section Key=value pairs below.
-m --make	When processing directories avoid unnecessary conversions.
-R --reset	Skip dk4gra.conf configuration file processing.
--help	Show short help text.
--manual	Show detailed help text.
--version	Show version information.
--license	Show license information.
--preference=value	Set a DK libraries version 4 preference, see [Preferences].

Key=value pairs

Key=value pairs specify configuration details.

For boolean settings it is sufficient to write the key 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.

Key	Type	Purpose	Default
level	Integer	PS language level when producing PS output, 2 or 3	3
dsc	Boolean	Write DSC comments (document structuring convention) to PS/EPS output files.	On for PS document output, off otherwise
lzw	Boolean	Allow LZW compression in PS level 2 output.	On
color	Boolean	Allow coloured output.	On
rgb-to-gray	String	Method to convert RGB data to grayscaled, see section RGB to gray conversion below.	bt601
rgb-to-cmyk	String	Method to convert RGB data to CMYK, one from "non-standard" or "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.	non-standard
alpha	String	Method for alpha channel use, either "mix" or "foreground".	mix
bg	RGB[:Boolean]	Default background colour, optionally a force flag appended. Normally the colour specified here is only used if the input image does not contain background colour information. The optional boolean flag decides about enforcing the background colour. Enforcing means the background colour is used even if there is background colour information in the input image file. I recommend to use the "force-bg" option instead of specifying the boolean flag here.	255:255:255
force-bg	Boolean	Flag to enforce specified default background colour.	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.	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.	On
dct-interpolation	Boolean	Set image interpolation flag when directly re-using DCT encoded data from JPEG files too.	Off
a-bpc	Boolean	Analyze bits per component. Reduce number of bits per component if reduction is possible without quality loss.	On
a-colour	Boolean	Analyze use of colours, switch output colour space to grayscaled if all pixels are gray.	On
a-alpha	Boolean	Analyze alpha channel use, avoid writing an SMask object to PDF output if all pixels are fully opaque.	On
paper	String	Paper size for documents. The paper size must be defined in a dk3paper.conf or dk4paper.conf file.	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).	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).	Off
resolution	String	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 backwards compatibility. Chunk is the default, instead of 1px1pt you should better use "i-res=on".	chunk
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".	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.	Off
rotate	Boolean	Allow image rotation by 90 degree if the rotated image fits better into the usable area.	Off
rsize	Boolean	Restrict output image dimensions to sizes LaTeX can handle	On for EPS/PDF images/objects Off otherwise
rsdct	Boolean	Allow direct re-use of DCT encoded data from JPEG files even if the image is scaled down due to size restriction	On

Alpha channel

PNG/TIFF/NetPBM 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 colour of each pixel, there are two choices:

Mixing the foreground colour as retrieved from input file against a background colour 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 colour information (background colour chunk) in the input image file is used by default, if present.

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

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

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

Compression and encoding

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

When producing PS level 2 output, LZW compression is enabled by default. If you disable LZW compression, run-length compression with separated colour channels is used if the number of bytes per colour channel per row does not exceed 16384.

For separated colour channels the data stream contains all red values for a row first, all green values next, all blue values finally. Without separated colour 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 colour 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 coloured 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 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 images use RGB, RGB+alpha or CMYK colour 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.

RGB to gray conversion

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

Variable/Operator	Used for
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
<<	Bit shift to the left.
>>	Bit shift to the right.
min{…}	Minium of listed values.
max{…}	Maximum of listed values.
median{…}	Median of listed values.

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

Name	Formula	Comments
bt601	E = (299 * R + 587 * G + 114 * B) / 1000	Keep luminance.
luminance	E = (30 * R + 59 * G + 11 * B) / 100	Same but shorter coefficients.
fast	E = (77 * R + 151 * G + 28 * B) >> 8	Fast calculation without division.
fastest	E = ((R << 1) + (G << 2) + G + B) >> 3	Yet faster, more inaccurate.
bt709	E = (2126 * R + 7152 * G + 722 * B) / 1000	Keep luminance, different coefficients.
average	E = (R + G + B) / 3	Average of components.
desaturation	E = (maximum{R,G,B} + minimum{R,G,B}) / 2	Results in low contrast image.
min	E = min{R,G,B}	Minimum decomposition.
median	E = median{R,G,B}	Median decomposition.
max	E = max{R,G,B}	Maximum decomposition.
red	E = R	Just use red component.
green	E = G	Just use green component.
blue	E = B	Just use blue component.

Image size, resolution and rotation

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.

LaTeX can only handle objects with dimensions smaller than 2³⁰ sp, this is slightly more than 16322 bp. When producing (E)PS/PDF images/objects a check is active whether the output image fits into 16322 bp in both width and height. Otherwise increased resolutions are assumed to produce smaller images. The rsize=off option disables the check.

Exit status

0 on success, all other status codes indicate an error.

Configuration

dk3paper.conf / dk4paper.conf

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

dk4gra.conf

This configuration file is used for graphics output from the DK tools project. 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

Cumulative processing is used. Settings made in a file processed earlier may be overwritten in files processed later.

You should place customized files only in the following directories:

${datadir}/dk4app-site,
${sysconfdir}/dk4app-site,
${datadir}/dktools-site,
${sysconfdir}/dktools-site,
${datadir}/bitmap2pp-site,
${sysconfdir}/bitmap2pp-site,
${HOME}/.dk4app,
${HOME}/.dk4app/dktools,
${HOME}/.dk4app/bitmap2pp

The following directories are managed by package management, you should not modify any file in these directories:

${datadir}/dk4app,
${sysconfdir}/dk4app,
${datadir}/dktools,
${sysconfdir}/dktools,
${datadir}/bitmap2pp

Versions

The bitmap2pp program replaces the bmeps and bmpp programs found in earlier versions of the DK tools project.
The initial version of the program was named bmeps.
After rewriting the program completely for version 4.12.0, the program was named bmpp.
It was renamed to bitmap2pp in version 4.33.0 to follow packaging guidelines for some Linux distributions requiring a minimum name length of 5 characters for commands in new packages.

Notes

When DCT encoded data from JPEG files is used directly, the entire JPEG file is embedded into PDF/PS/EPS output.
JPEG files can contain EXIF data providing additional information about the images. This might include camera type and serial number, creation timestamp and geographic position…
When worried about privacy you might want to use special software (i.e. exiftool) to inspect or modify the EXIF data in the JPEG files you use. Alternatively you can use dct=off to deny direct re-use of data from JPEG files.

Restrictions

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

Examples

Create PDF object

To create PDF object screenshot.pdf for use with pdfLaTeX from file screenshot.png:

bitmap2pp -l pdf screenshot.png

Create EPS object

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

bitmap2pp -l eps screenshot.png

Create PDF document

To create PDF file fax.pdf for printing from file fax.tif:

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

Create PS document

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

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

Create PDF image

To create file.pdf for standalone viewing from file file.png:

bitmap2pp -l pdf.image file.png

Create PS image

To create standalone image file.ps from file.png:

bitmap2pp -l ps.image file.png

FAQ

How do I switch PS language level to 2?

For one command invokation
Use "-lps,level=2" instead of "-lps".

Permanently
Create or modify one of the following dk4gra.conf files:

File	Sets defaults for
DATADIR/dk4app-site/dk4gra.conf	all users
SYSCONFDIR/dk4app-site/dk4gra.conf	all users
HOME/.dk4app/dk4gra.conf	current user

DATADIR is typically /usr/share or /usr/local/share on Unix/Linux, C:\Program Files\Krause\share on Windows.
SYSCONFDIR is typically /etc or /usr/local/etc on Unix/Linux, C:\Program Files\Krause\etc on Windows.
HOME is the users home directory on Unix/Linux, the user profile directory on Windows.

To configure PS level 2, add the following contents:

[ps]
level=2

How do I disable 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 patents in most EU countries expired in 2004. In bitmap2pp LZW compression is now enabled by default when producing PS level 2 output, but can be disabled.

For one command invokation
Use "-lps,level=2,lzw=no" instead of "-lps,level=2".

Permanently
Create or modify a dk4gra.conf file (see question above where to locate the file). Add the following contents:

[ps]
level=2
lzw=off

How do I change the default paper format for documents?

For one command invokation
Use "-lps.document,paper=letter" instead of "-lps.document".