NAME

pcltrans − translate a Starbase bitmap file into PCL or RTL raster graphics format. 

SYNOPSIS

pcltrans [ options ] <file>

DESCRIPTION

The command pcltrans translates data from a Starbase bitmap file into either Printer Command Language (PCL) or Raster Transfer Language (RTL) raster graphics format.  Output from pcltrans is a series of PCL and/or RTL commands which consist of binary data and escape sequences appropriate for the target output device.  Both PCL and RTL (a subset of PCL used by large-format plotters) are printer languages recognized by a large number of color and monochrome printers, including Hewlett-Packard plotters.  Since output is to standard out, pcltrans should be used as a filter with its output redirected to a file or to some other process such as the lp spooler.  If input is redirected through a pipe, then pcltrans will create a temporary file for use by the formatter. 

pcltrans operates in one of four basic modes, each of which corresponds to the level of image processing provided, and where that image processing occurs (either within pcltrans or within the hardcopy device).  These image processing modes are as follows:

a) PCL device performs resolution-independent scaling
b) RTL device performs resolution-independent scaling
c) host system performs resolution-independent scaling
   (for PCL devices only)
d) host system performs minimal scaling (for PCL devices
   only)

The importance of the type of image processing performed becomes evident when one considers that the usual resolution of the input image is about 1Kx1K pixels, and the resolution of the output image can be significantly higher (such as 10Kx15K pixels for the DesignJet 650C). Many high-end devices (such as the PaintJet XL300 and the DesignJet 650C) support high-quality, resolution-independent image processing in the device itself.  In these devices, complex algorithms such as error diffusion or ordered dither provide high-quality output from the Starbase bitmap file.  Other devices (such as the DeskJet 320) do not have these capabilities, so this image processing must be performed on the host system. 

Refer to the section on "Selecting an Imaging Mode" for more information on each of these imaging options. Note that various additional options are available once an imaging option has been selected. Detailed information on the options appropriate for each imaging mode appears later in this document. 

WARNING: If a PCL/RTL output file containing imaging commands is sent to a device that does not understand this functionality, the output will be incorrect. 

SELECTING AN IMAGING MODE

In general, the primary criteria for selecting an imaging mode with pcltrans is the imaging capabilities of the target device. The user has four options, as described here:

−I Select this option to specify that the PCL device performs resolution-independent image processing.  This option is recommended for PCL devices which have internal imaging capabilities, and includes devices such as the PaintJet XL/XL300, the DeskJet 1200C, and the Color LaserJet.  If the output device has color capabilities, the image is rendered in color by default, and the output device renders the image at its highest possible resolution.  By default, the output image is scaled for the best fit on the size of media loaded on the output device.  The output size may be altered by explicitly setting the width and/or height of the output image (using the -d and/or -h sizing options), or setting a pixel expansion factor (using -e).  Setting the width and/or height of the ouput image has precedence over setting the pixel expansion factor.  For more information on the complete set of options available with this mode, refer to the section "Options for PCL Device Imaging."

−Z Select this option to specify that the RTL device performs resolution-independent image processing.  This option is the only pcltrans imaging option which works with RTL devices with internal imaging capabilities, and includes devices such as the DesignJet 650C.  If the output device has color capabilities, the image is in color by default.  The output device renders the image at its highest possible resolution, and by default the output image is scaled for the best fit on the size of media loaded into the output device.  If isotropic scaling is desired (which preserves the aspect ratio of the original image), then the user should either (a) use the default size (no sizing options specified), or (b) select at most one of the sizing options, -d or -h.  Specifying both -d and -h results in anisotropic scaling to that size.  For more information on the complete set of options available with this mode, refer to the section "Options for RTL Device Imaging."

−C Select this option to specify that the host computer performs resolution-independent image processing (PCL).  This option is intended for devices which do not have image processing capabilities. This includes color printers such as the DeskJet 320 and the DeskJet 500 series, as well as monochrome devices such as the LaserJet II, LaserJet III, and LaserJet 4 family of printers.  With this option, each pixel is converted to the appropriate output color value using an error diffusion algorithm (by default).  The −a option overrides the default imaging algorithm.  For more information on the complete set of options available with this mode, refer to the section "Options for Host-Based Imaging."

<none>
The user specifies minimal host image processing by not selecting either -I, -Z, or -C.  This method is intended for those situations where minimal processing of the Starbase bitmap file is required.  This would include situations where a small output image is desired (one-for-one pixels), or when the output of pcltrans will be saved for later printing or incorporated into other documents.  Here, minimal transformations on the input data are performed; some simple pixel replication is available with this option, if desired.  This option generates only monochrome output.  For more information on the complete set of options available with this mode, refer to the section "Options for Minimal Host-Based Imaging."

OPTIONS FOR PCL DEVICE IMAGING (-I)

The following options are available when the user has selected PCL device imaging (-I).  Refer to the section "Selecting an Imaging Mode" for more information on the use of this imaging mode. 

Rendering Options:

−an Rendering algorithm used by the hardcopy device for scaling the image.  This value is passed to the device, which performs the image rendering.  The possible values of n are:

0 = no algorithm applied
1 = set color to nearest printer PRIMARY
2 = set all black pixels to white and all other colors
    to black (can use for text screen dumps)
3 = color ordered dither (default)
4 = color error diffusion
5 = monochrome ordered dither
6 = monochrome error diffusion

−n White values are printed black, and the background is not printed. This option is invalid when -a is also specified. 

Positioning Options:

−R Output print orientation is left to right across the width of the paper (portrait mode).  Default orientation is left to right across the length of the paper (landscape mode).  Raster rotation is performed by pcltrans rather than within the printer. 

−s Raster graphics is started at the current printer cursor position. 

−xinches
Amount to offset the image from the printable area of the output device, x inches from the left boundary.

−yinches
Amount to offset the image from the printable area of the output device, y inches from the top boundary.

Sizing Options:

−dinches
Width of the destination image in inches.

−eexpansion factor
Pixel expansion factor (an integer value) for the destination image.

−hinches
Height of the destination image in inches.

−msize
Page size selection for the PaintJet XL300:

Size	Standard Size	Dimensions
A	ANSI A size	8.5 × 11 inches (English default)
legal	legal size	8.5 × 14 inches
B	ANSI B size	11 × 17 inches
A4	ISO A4 size	210 × 297 mm (metric default)
A3	ISO A3 size	297 × 420 mm

−rdots/inch
Printer resolution to use, specifed in dots per inch. Note that this option is ignored on those devices which do not support multiple output resolutions.

Background/Foreground Options:

−bbcol
Background color table index for printing a single plane. All 0’s in the plane will be rendered using the color specified by this index. The default background color table index is 0. This option only has effect when printing a single plane as specified with the −p option. 

−ffcol
Foreground color table index for printing a single plane. All 1’s in the plane will be rendered using the color specified by this index. The default foreground color table index is 1. This option only has effect when printing a single plane as specified with the −p option. 

−k Don’t print the background color.  Default is to print the background color. 

Image Reproduction Options:

−gvalue
Gamma correction value to apply to the image. Default gamma value is 0.8; reasonable values for gamma typically range between 0.0 and 2.0.

−Kkbytes
Amount of memory in kilobytes dedicated to processing the image. Processing time usually decreases as dedicated memory size increases. However, if the user specifies a value which is larger than the amount of physical memory, the processing will actually be slower due to virtual memory activity.

−pplane
Bitmap plane to be printed when only a single plane is to be printed. The default is to print a full-depth bitmap. If the plane number specified in this option is non-negative and is not contained in the bitmap file, the pcltrans formatter will exit with an error.  If the plane number specified in this option is negative, the formatter will default to process all planes. 

−q Presentation mode quality.  A higher quality mode available with many ink jet technology printers. 

−T Print on transparency film. 

−zopt
Scale algorithm to apply to the image, only if the destination image is smaller than the source in pixels. The possible values of opt are:

0 = algorithm to apply to an image with a light background
1 = algorithm to apply to an image with a dark background

OPTIONS FOR RTL DEVICE IMAGING (-Z)

The following options are available when the user has selected RTL device imaging (-Z).  Refer to the section "Selecting an Imaging Mode" for more information on the use of this imaging mode. 

Rendering Options:

−an Image rendering algorithm desired for those devices which support multiple rendering algorithms (such as the DesignJet 650C).  This value is passed to the device, which performs the image rendering.  For the DesignJet 650C the possible values of n are:

3  = color ordered dither (default)
17 = color error diffusion

Sizing Options:

−dinches
Width of the destination image in inches. Default width is the width of the media loaded on the device.

−hinches
Height of the destination image in inches, measured in the direction of the paper motion. Default height is the height of the media loaded on the device (sheet media), or 1.5 times the width of rollfeed media.

Image Reproduction Options:

−zopt
Scale algorithm to apply to the image, only if the destination image is smaller than the source in pixels. The possible values of opt are:

0 = algorithm to apply to an image with a light background
1 = algorithm to apply to an image with a dark background

OPTIONS FOR HOST-BASED IMAGING (-C)

The following options are available when the user has selected host-based imaging (-C).  Refer to the section "Selecting an Imaging Mode" for more information on the use of this imaging mode. 

Rendering Options:

−an Rendering algorithm desired for the image.  pcltrans performs the image processing on the host computer system.  The possible values of n are:

0 = no algorithm applied
1 = set color to nearest printer PRIMARY (same as -c)
2 = set all black pixels to white and all other colors
    to black (can use for text screen dumps)
3 = color ordered dither
4 = color error diffusion (default)
5 = monochrome ordered dither
6 = monochrome error diffusion

−c Each pixel is converted to the nearest PRIMARY color (red, green, blue, cyan, magenta, yellow, white, or black).  The effect of specifying −c is the same as the −a1 option.  Note: the −a option overrides this option. 

−j For the DeskJet 500C and 550C, produce composite black output (cyan + magenta + yellow).  This option generates output which uses only the CMY cartridge, and does not use the black cartridge.  Contrast with the -J option. 

−J For the DeskJet 550C only, produce true black output.  This option generates output which uses both the CMY and black cartridges.  Contrast with the -j option. 

Positioning Options:

−R Output print orientation is left to right across the width of the paper (portrait mode).  Default orientation is left to right across the length of the paper (landscape mode).  Raster rotation is performed by pcltrans rather than within the printer. 

−s Raster graphics is started at the current printer cursor position. 

−xinches
Amount to offset the image from the printable area of the output device, x inches from the left boundary.

−yinches
Amount to offset the image from the printable area of the output device, y inches from the top boundary.

Sizing Options:

−dinches
Width of the destination image in inches.

−eexp
Pixel expansion — indicates the expansion for each pixel in the bitmap and ranges from 1 to 8.  For example, to expand from a single pixel to a 4x4 cell, set the expansion parameter to 4. The default pixel expansion factor is 1.

−hinches
Height of the destination image in inches.

−P The output image is scaled for the best fit on the size of media loaded in the device. 

Background/Foreground Options:

−bbcol
Background color table index for printing a single plane. All 0’s in the plane will be rendered using the color specified by this index. The default background color table index is 0. This option only has effect when printing a single plane as specified with the −p option. 

−ffcol
Foreground color table index for printing a single plane. All 1’s in the plane will be rendered using the color specified by this index. The default foreground color table index is 1. This option only has effect when printing a single plane as specified with the −p option. 

−k Don’t print the background color.  Default is to print the background color. 

Image Reproduction Options:

−gvalue
Gamma correction value to apply to the image. Default gamma value is 0.8; reasonable values for gamma typically range between 0.0 and 2.0.

−Kkbytes
Amount of memory in kilobytes dedicated to processing the image. Processing time usually decreases as dedicated memory size increases. However, if the user specifies a value which is larger than the amount of physical memory, the processing will actually be slower due to virtual memory activity.

−pplane
Bitmap plane to be printed when only a single plane is to be printed. The default is to print a full-depth bitmap. If the plane number specified in this option is non-negative and is not contained in the bitmap file, the pcltrans formatter will exit with an error.  If the plane number specified in this option is negative, the formatter will default to process all planes. 

−zopt
Scale algorithm to apply to the image, only if the destination image is smaller than the source in pixels. The possible values of opt are:

0 = algorithm to apply to an image with a light background
1 = algorithm to apply to an image with a dark background

OPTIONS FOR MINIMAL HOST-BASED IMAGING

The following options are available when the user has selected minimal host-based imaging.  Refer to the section "Selecting an Imaging Mode" for more information on the use of this imaging mode. 

Rendering Options:

−c Each pixel with a non-zero RGB value is converted to black.  Default is conversion to the nearest available shade of gray. 

Positioning Options:

−R Output print orientation is left to right across the width of the paper (analogous to portrait mode on the LaserJet printer).  Default is left to right across the length of the paper (landscape mode).  Raster rotation is performed by pcltrans rather than within the printer. 

−s Raster graphics is started at the current printer cursor position. 

Sizing Options:

−eexp
Pixel expansion — indicates the expansion for each pixel in the bitmap and ranges from 1 to 8.  For example, to expand from a single pixel to a 4x4 cell, set the expansion parameter to 4. The default pixel expansion factor is 1.

−llength
Length of the paper in inches. The default paper length is 10.5 inches.

−rdots/inch
Target printer resolution specifed in dots per inch.

−wwidth
Width of paper in inches. The default paper width is 8.0 inches.

Background/Foreground Options:

−bbcol
Background color table index for printing a single plane. All 0’s in the plane will be rendered using the color specified by this index. The default background color table index is 0. This option only has effect when printing a single plane as specified with the −p option. 

−ffcol
Foreground color table index for printing a single plane. All 1’s in the plane will be rendered using the color specified by this index. The default foreground color table index is 1. This option only has effect when printing a single plane as specified with the −p option. 

−k Don’t print the background color.  Default is to print the background color. 

Image Reproduction Options:

−pplane
Bitmap plane to be printed when only a single plane is to be printed. The default is to print a full-depth bitmap. If the plane number specified in this option is non-negative and is not contained in the bitmap file, the pcltrans formatter will exit with an error.  If the plane number specified in this option is negative, the formatter will default to process all planes. 

RUN COMMANDS (rc) FILE

pcltrans will also accept options from a run commands file.  Before processing the command line arguments, pcltrans looks for a run command file as follows:

1.  If there is a file in the current working directory named .pcltransrc, then read and process its contents. 

2.  Otherwise, if there is a file in the user’s home directory named .pcltransrc, then read and process its contents. 

3.  Otherwise, read and process the file /usr/lib/starbase/formatters/pcl/pcltransrc, which is installed with the Starbase product.  This file contains reasonable defaults that should not alter the behavior of pcltrans from previous releases. 

The rc file contents essentially follow the same format as command line options.  Each line of the rc file should be:

1.  Blank (or just spaces and tabs), or

2.  A comment, indicated by a ’#’ in the first column, or

3.  An option, with appropriate arguments, exactly as it would be given on the command line. 

Command line arguments override those specified in the rc file. 

NOTE: Command line options will not override certain option settings in the rc file, namely −I, −c, −C, −R, −s, −P, −k, −q, and −T. 

EXAMPLES

All examples shown here assume that output can be directed to the target output device via the lp spooler.  A hypothetical printer destination has also been provided for each example. 

A typical example is to format a file for output to a Color LaserJet or a PaintJet XL300.  Color error diffusion is performed by the hardcopy device (rather than by pcltrans), using a gamma correction value of 0.6.  Output uses presentation mode quality, and is piped to the lp spooler. 

pcltrans -I -a4 -g0.6 -q myfile | lp -oraw -dxl300

Another example is to format a file for output to a DesignJet 650C (large format inkjet device).  Color error diffusion is used, and the image is scaled to fit in a 10-inch by 10-inch area (which may result in anisotropic scaling if the original image does not have an equal number of pixels in both the x and y dimensions).  Color error diffusion is used, and the output is piped to the lp spooler. 

pcltrans -Z -d10. -h10. -a17 myfile | lp -oraw -ddj650c

Another example is formatting a file for monochrome output to a DeskJet 550.  The desired plot orientation is left to right across the width of the page.  Black pixels are snapped to white, and all other colors are snapped to black (appropriate for dumping text and line drawings). Output is then directed to the lp spooler. 

pcltrans -C -a2 -R myfile | lp -oraw -ddj550

SEE ALSO

Starbase Reference: bitmap_to_file(3G), bitmapfile(4G), file_print(3G), screenpr(1G). 
Starbase Graphics Techniques: "Storing, Retrieving, and Printing Images". 
Starbase Device Drivers Manual: "PCL Formatter", "PCL Imaging Formatter". 
HP-UX Reference: lp(1M). 

 

Hewlett-Packard Company  —  HP-UX Release 10.0: November 1994