Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
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

       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...]
	   specifies output driver and output mode. The	optional key=value
	   pairs can be	used for further configuration.	 See section
	   "key=value pairs" below.

	   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.

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

	   shows a short help text.

	   shows a detailed help text.

	   shows the version number.

	   shows the license conditions	of both	bitmap2pp and the used

       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:

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

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

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

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

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

	   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.

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

	   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.

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

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

	   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.

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

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

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

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

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

	   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.

	   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.

	   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

	   number  The specified floating point	number is used as resolution
		   in dpi for both x and y direction.

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

	   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.

	   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.

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

	   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.

	   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:

       o   Mixing the foreground color as retrieved from input file against a
	   background color considering	opaqueness from	alpha channel.	This
	   is the default.

       o   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

       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:

	   Keep	luminance:

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

	   Keep	luminance, use shorter coefficients:

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

	   Fast	calculation without division operations:

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

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

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

	   Keep	luminance, use other coefficients:

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

	   Average of red, green, blue:

		   E = (R + G +	B) / 3

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

	   Just	use the	green component:

		   E = G

	   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:

       o   Keep	the aspect ratio (default), probably leaving parts of the
	   available area unused.

       o   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 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 from file.png file:
	     bitmap2pp -l ps.image file.png

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

       o   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

		   ${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:


       o   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


       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.

	   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:

	   o	   ${datadir}/dk4app/dk4gra.conf

	   o	   ${sysconfdir}/dk4app/dk4gra.conf

	   o	   ${datadir}/dk4app-site/dk4gra.conf

	   o	   ${sysconfdir}/dk4app-site/dk4gra.conf

	   o	   ${datadir}/dktools/dk4gra.conf

	   o	   ${sysconfdir}/dktools/dk4gra.conf

	   o	   ${datadir}/dktools-site/dk4gra.conf

	   o	   ${sysconfdir}/dktools-site/dk4gra.conf

	   o	   ${datadir}/bitmap2pp/dk4gra.conf

	   o	   ${sysconfdir}/bitmap2pp/dk4gra.conf

	   o	   ${datadir}/bitmap2pp-site/dk4gra.conf

	   o	   ${sysconfdir}/bitmap2pp-site/dk4gra.conf

	   o	   ${HOME}/.dk4app/dk4gra.conf

	   o	   ${HOME}/.dk4app/dktools/dk4gra.conf

	   o	   ${HOME}/.dk4app/bitmap2pp/dk4gra.conf

	   o	   ./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

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

       o   The file must be compliant to the "TIFF baseline v6.0 standard".

       o   The number of bits per component must be 8 or less.

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

	   The pnmtops program from the	NetPBM project - see
	   <> - converts NetPBM input files to PS
	   and EPS.

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

	   How to define paper sizes.

	   Syntax of dk4gra.conf files.

	   Project homepage.

4.32.0				  2022-02-17			  bitmap2pp(1)


Want to link to this manual page? Use this URL:

home | help