NAME

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

SYNOPSIS

pcltrans [ options ] <file>

DESCRIPTION

The command pcltrans translates bitmap (raster graphics) data from Starbase bitmap file format into Printer Command Language (PCL) raster graphics format.  Since output is to standard out, screenpr should be used as a filter with 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. 

Output is a series of PCL commands which consist of binary data and escape sequences as described here.  (<esc> is the escape character, ASCII 0x027.)  The first command in the output is <esc>*t#R (to set graphics resolution), followed by <esc>*r1A (to start raster graphics).  Next follow individual rows of raster data prefixed with <esc>*b#W[raster data] (to transfer raster graphics).  The final command in the output is <esc>*rB (to terminate raster graphics).  Last of all, screenpr sends a form feed character. 

In addition, RGB pixels are converted to shades of gray based on their intensity values.  If pixels are not expanded, the output is left to right across the long dimension of the paper, and resolution is 300 dots per inch. 

When PCL imaging functionality is invoked (via the −C or −I option), the image is rendered using ordered dither and a gamma correction value of 0.8 (This is the default rendering algorithm.).  The output is from left to right across the long dimension of the paper. The −I option is used with printers having built-in imaging functionality.  ("-I" option invokes the PCL imaging formatter.)  The −C option can be used with printers having built-in  imaging, or with printers that do not have built-in imaging.  (See the introduction and comparison sections of the Starbase Device Drivers Manual.) 

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

COMMAND LINE ARGUMENTS

Imaging Option:

−C Each pixel is converted to the appropriate output color value using an error diffusion algorithm. This option also changes the effect of the −c option.  Not all PCL printers support color mode.  The −a option overrides the default algorithm. 

−I The output image is scaled for the best fit on the size of media loaded in the device.  If the output device has color capabilities, the image is in color by default. The data is left in RGB format and the output device prints the output in color.  The output device renders the image at its highest possible resolution, and the output image is scaled for the best fit on the size of media loaded into the output device. 

Rendering Options:

−an Render algorithm desired.  Valid only in conjunction with the −C or −I option.  The possible values of n are:

0 = no algorithm applied
1 = snap to printer PRIMARIES (same as specifying −c and −C together)
2 = snap black to white and all other colors to black
    (can use for text screen dumps)
3 = color ordered dither (default)
4 = color error diffusion (same as the −C option)
5 = monochrome ordered dither
6 = monochrome error diffusion

−c Each pixel with a non-zero RGB value is converted to black.  Default is conversion to the nearest available shade of gray. 
This option has a different effect if the −C option is also specified.  In that case, each pixel is converted to the nearest PRIMARY color (red, green, blue, cyan, magenta, yellow, white, or black).  (The effects of specifying −c and −C together is the same as for the −a1 option.  Note: the −a option overrides this combination.) 

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 changing printer modes. 

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

−xinches
Destination image offset, x inches from the left boundary.  Valid only in conjunction with the −C or −I option. 

−yinches
Destination image offset y inches from the top boundary.  Valid only in conjunction with the −C or −I option. 

Sizing Options:

−dinches
Width of the destination image in inches.  Valid only in conjunction with the −C or −I option. 

−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 is 1.

−hinches
Height of the destination image in inches.  Valid only in conjunction with the −C or −I option. 

−llength
Length of the paper in inches. Not valid when −C or −I are also specified.  The default is 10.5 inches. 

−P The output image is scaled for the best fit on the size of media loaded in the device.  Valid only in conjunction with the −C option. 

−rdots/inch
Printer resolution specifed in dots per inch.  Ignored when using −C or −I option. 

−wwidth
Width of paper in inches. Not valid when −C or −I are also specified.  The default is 8.0 inches. 

Background/Foreground Options:

−bbcol
Background color table index for printing a single plane. The default 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. The default 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.  Use of the background_color_index call will cause unexpected results with this option. 

Image Reproduction Options:

−gvalue
Gamma correction value to apply to the image.  Accepted values may range between 0.0 and 2.0. This is valid only in conjunction with the −C or −I option. 

−Kkmem
Amount of memory in kilobytes dedicated to processing the image.  Processing time decreases as dedicated memory size increases. However, if the user specifies a larger amount of memory than is available, the processing will actually be slower due to virtual memory activity.  This is only valid in conjunction with the −C or −I option. 

−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 available on the ink jet technology printers.  Valid only in conjunction with the −I option. 

−T Print on transparency film.  Valid only in conjunction with the −I option. 

−zopt
Scale algorithm to apply to the image, only if the destination image is smaller than the source in pixels.  Valid only in conjunction with the −C or −I option.  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

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: −I, −c, −C, −R, −s, −P, −k, −q, and −T. 

EXAMPLES

A typical case is formatting a file for output at 150 dots per inch resolution to a LaserJet Plus printer.  The desired plot orientation is left to right across the width of the page.  The output in this example is then piped to lp in raw mode so that no processing of the data is performed by lp. 

pcltrans -r150 -R myfile | lp -oraw

Another typical example is to format a file to print with imaging capabilities invoked, color error diffusion, a gamma correction value of 0.6, with presentation mode, and piped to the LP spooler. 

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

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 9.0: August 1992