FreeBSD Manual Pages
bitmap2pp(1) DK tools and libraries bitmap2pp(1) NAME bitmap2pp - Bitmap to PDF/PS converter SYNOPSIS bitmap2pp -ldriver[.mode][,name=value...] options file(s) 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. 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 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: on 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. ALPHA CHANNEL 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. COMPRESSION AND ENCODING Flate compression is used for PDF output and PS level 3 output. LZW compression is used for PS level 2 output by default. You can disable LZW compression and use run length compression with separated color channels instead. If LZW compression is disabled and the number of bytes per color channel per row exceeds 16384, no compression is used. 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 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. COLOR SPACE CONVERSION 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 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. EXIT STATUS 0 on success, all other values indicate errors. 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? 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 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 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. On the command line Use "-lps,level=2,lzw=off" instead of "-lps,level=2". In a dk4gra.conf file Create a file dk4gra.conf containing the following lines: [ps] level=2 lzw=off 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: • ${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 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. AUTHORS Dirk Krause HISTORY 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. COPYRIGHT AND LICENSE The ``DK tools and libraries'' project (abbreviated: ``dktools'') uses a BSD style license, see dktools-legal(1) for details. 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. 4.35.3 2023-04-06 bitmap2pp(1)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | KEY=VALUE PAIRS | ALPHA CHANNEL | COMPRESSION AND ENCODING | IMAGE ANALYSIS | COLOR SPACE CONVERSION | IMAGE SIZE, RESOLUTION AND ROTATION | EXIT STATUS | EXAMPLES | FAQ | FILES | RESTRICTIONS | AUTHORS | HISTORY | COPYRIGHT AND LICENSE | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=bitmap2pp&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>