The mode switch `-m string' tells hp2xx about the mode it should use to generate output, i.e., the desired output format. hp2xx can run in three different groups of modes: Generating vector graphics, raster graphics, or "preview mode", i.e., displaying the graphics. Preview is the default; see section Option summary for a list of all modes.
Sizing your output.
NOTE: The basic unit length within hp2xx is mm (millimeter). This unit is always assumed except where noted otherwise.
In contrast to a real HP-GL plotter, hp2xx lets you decide freely about the size of the picture. While preserving the picture's aspect ratio, hp2xx will fit the picture into a window of width w and height h. By default, w = h = 200 (mm). Set these basic sizes using options `-w w' and `-h h'.
Sometimes you'll want to change the aspect factor of a picture, e.g., to spread out a square picture into landscape. Option `-a af' is used for this. af > 1 increases x/y ratio, 0 < af < 1 decreases x/y.
Example: Let's assume your picture covers a native coordinate range of 100...900 plotter units in x direction and 200...600 in y direction. Thus, its width is double its height. Using defaults, hp2xx will create a picture of size 200 x 100 mm, while options `-w 100 -h 40' will lead to a picture of size 80 x 40 mm, and `-w 100 -h 40 -a 0.5' results in a 40 x 40 mm picture.
Alternatively, ignore explicit size control and rely on the true HP-GL coordinates (and therefore: sizes) of the given input file(s). Flag `-t' inhibits `-a -h -w' and lets hp2xx use true HP-GL sizes, based on the assumption that 1 HP unit = 1/40 mm.
Some modes of hp2xx support page offsets, i.e., left and upper margins added to the picture, probably in addition to some hard margins which cannot be avoided. Currently, these modes are eps, pcl, and pre. The left margin (offset) is modified with option `-o off_left', while the upper margin can be controlled via `-O off_upper'. off_left and off_upper are specified in mm.
Pen sizes and colors.
Imagine a plotter with a pen carousel, e.g., like the model HP7550A. The carousel carries a (small) number of pens. Their colors and tip thicknesses (sizes) are selected by a human operator, while the plotter only receives commands like "Now use pen number 5". If you don't provide a pen, the plotter will move and "draw" without this pen if its number is selected.
hp2xx emulates a carousel of up to 8 pens of various colors and sizes. By default, all pens are present, have foreground color (typically black), and their tip thicknesses are one unit (here: 1/10 mm for vector modes, 1 pixel for raster modes).
Pen colors and sizes are represented by digits to allow for a compact option list. There are 8 colors including background (usually white). See section Option summary for a list of all colors. E.g., color 3 is green, and color 7 means yellow. Permitted pen sizes are 0 ... 9 units. WARNING: In raster modes, all pen sizes larger than 4 units (pixels) will be clipped to 4 units!
Options `-c c-string' and `-s s-string' tell hp2xx about the pens to be placed in the carousel. c-string and s-string are strings of 1 to 8 digits, corresponding to special choices of pen 1 to 8. Defaults are c-string = s-string = `11111111'. If you specify less than 8 pens, the remaining pens keep their defaults.
hp2xx -p13 foo.hp
Show a preview of `foo.hp', drawing all lines with pen #2 three pixels wide instead of default 1 pixel, which applies to all other pens.
hp2xx -c12740 -p12230412 foo.hp
Here, pen #5 is "removed". Pens #1 and #7 keep their default sizes, all others are set to various sizes. Pen #2 is red, #3 is yellow, and #4 is blue, while all other pens keep `foreground' color, e.g., black.
Selecting a page.
There is a HP-GL command named `PG;' which amounts to a FormFeed. Thus, there are multi-page HP-GL sources. While hp2xx was designed for just one output picture per input file, there is a simple way to cope also with multi-page sources:
hp2xx keeps track of the number of encountered `PG;' commands. All code up to the next (if any) `PG;' command is considered a single page. Pages are counted, starting at 1. You can ask hp2xx to ignore all HP-GL commands other than on page n with option `-P n', effectively filtering out any one-page graphics. Sometimes, converting a whole page range makes sense, too. Therefore, hp2xx also accepts page ranges via `-P n1:n2'. The default is `-P 0' which selects all pages.
WARNING: Some HP-GL sources may start with a `PG;' so the first page of your graphics may be 2 instead of 1. Look for the number of encountered pages in the diagnostic output if you miss the expected page! If the detected coordinate range shows unreasonable numbers like 1e10, you'll be probably looking at an empty page.
All HP-GL graphics are decomposed by hp2xx into elementary move and draw commands. Selecting a vector mode essentially defines the conversion rules of such commands into specific formats.
The most popular and versatile vector format currently is Encapsulated PostScript (EPS). (In fact, it's much more than just a vector graphics format, but hp2xx uses only EPS's line drawing features.) Many programs allow importation of EPS files, and PostScript gives excellent printing results, so `-m eps' is highly recommended.
Currently, all other supported vector formats represent various compromises to persuade TeX or LaTeX into the generation of graphics. See section TeX formats, if you are specially interested in TeX.
Raster graphics are probably the most widely used graphics by now. Many publishing programs accept rasterized graphics. It's likely you'll use hp2xx primarily in some raster mode.
In addition to vector modes, all raster modes need the desired resolution of an assumed underlying pixel grid to plot on, i. e., the number of pixels per unit length within that grid. A traditional measure is the number of "dots per inch" (DPI). hp2xx makes an exception from its usual unit length mm and lets you specify the traditional DPI values. Option `-d num' affects both x and y direction, num being the DPI value (an integer). if `-D num_y' is also specified, num_y will override the num DPI value, but only for the y direction.
There are plenty of raster formats on various platforms, much more than hp2xx will ever handle. The supported raster formats IMG, PBM, PCL, PCX were chosen for their widespread use, their simplicity, for actual demand, and for accessibility of specifications. If your desired format is not supported, look for a converter. E.g., the Portable Bitmap (PBM) project offers quite a variety of such converters.
Please note that the preview mode (which does not create any output file) is a special raster mode. Instead of going into some output file, the internal bitmap is transferred into display memory. Therefore, the above considerations apply also to preview mode.
Currently, there is only one printer format (not counting `eps', which is printable on PostScript printers): `pcl', which stands for HP PCL Level 3. Essentially it is a raster format, but it comes with a few restrictions and additional options which correspond to printer properties. It prints on HP Laserjet and HP Deskjet series printers and compatibles.
The restriction concerns the resolution (DPI) during rasterization. Due to printer hardware limitations, only `-d 75', `-d 100', `-d 150', and `-d 300' are permitted; option `-D' must not be used.
There are two flags which may be useful if the output goes directly to a printer: Option `-i' initializes the printer before the output starts, and `-F' sends a FormFeed (ASCII 12) after the output.
For the HP Deskjet printer series, there is support of some "special" commands; `-S 1' activates these. There is a limited support of color modes available, too: For the DJ500C or DJ550C models, hp2xx can generate both CMY-based and CMYK-based color output (if colors are used: see option `-c'). Supply option `-S 3' for CMY color mode, and option `-S 4' for CMYK color mode (for the DJ550C). The Deskjet modes automatically invoke TIFF compression (mode 2), while pure PCL Level 3 does not know about compression.
Preview mode is hp2xx's default. Its use prior to all other conversions is recommended since it offers a good impression of your final results. Functionally it is also a raster mode.
Depending on your hardware and operating system platform, hp2xx uses one of a variety of preview modules. On GUIs, a window containing the graphics will pop up, while on other systems the whole screen may be used for preview. You can control the position of a preview window via options `-o' and `-O' in a natural way. In full-screen previews, unused spaces are padded to the right and bottom with background color.
Since there is no way for hp2xx to predict the actual size and resolution of your preview device, e.g., screen, you may have to gauge hp2xx's preview mode (using options `-whdD'). For example, if your device effectively works at 86 DPI and offers an active area of 24 by 18 cm,
hp2xx -d86 -w240 -h180 foo.hp
will make maximum use of your screen area and give you correct sizes. Since a single gauge will do for all future calls, you'll probably want to create some one-line batch file for invoking hp2xx in preview mode, correctly gauged for your screen.
Depending on page offsets and the selected sizes and resolutions, a preview may not fit on your screen. In that case, some preview modules simply clip the picture; others give a warning but let you continue (DOS), and others simply terminate -- so don't start too large.
DOS users: Most VGA cards offer high-resolution modes (SVGAs). Unfortunately, there is no software standard for these modes. hp2xx lets you utilize these modes anyway with just a little help from you. Tell hp2xx the so-called mode byte of your favorite hi-res mode via option `-V num'. Since hp2xx issues only standard BIOS calls for mode switching, setting of color look-up table entries, and pixel drawing, chances are good that your VGA card's hi-res modes will work!
WARNING: You can damage your hardware by specifying inappropriate VGA modes! Generally you'll need a monitor which can sync on the horizontal frequency of the selected VGA hi-res mode, e.g., a multi-scan monitor. In case of doubt, switch off your monitor immediately!!
hp2xx features an on-line options summary. Invoking hp2xx with option `-H', or with any illegal option or without any parameter, will display about 2 pages of text. (Note: I'd have preferred option `-h' for on-line help, but this option is needed by the indispensable height parameter.)
During operation, hp2xx outputs various information about the current HP-GL file and about hp2xx's actions. As usual, all this goes to stderr. You can re-direct these diagnostics into a file even without any help from a UNIX shell by specifying a log file using option `-l logfile', or you may switch off diagnostics completely with option `-q' (`quiet' mode). NOTE: Using both options as in `-q -l logfile' is of no use as it will result in an empty logfile.
Finally, there is a simple way to rotate whole pictures: Option `-r angle' rotates the picture counter-clockwise by the supplied angle (given in degrees). E.g.,
hp2xx -r90 foo.hp
will show the picture rotated by 90 degrees, letting vectors originally pointing left-to-right now point botttom-to-top. This may be handy e.g. for printing in landscape format. NOTE: The limiting rectangle supplied by `-hw' is not affected by `-r', so in order to obtain e.g. a full-page landscape picture on an A4 page, issue a command similar to:
hp2xx -m pcl -d 150 -r90 -h270 -w160 landscape.hp