pl(1)

Section: Misc. Reference Manual Pages (PL)
Updated: 02-JUN-2006 PL ploticus.sourceforge.net
Index

Name

Synopsis

pl -prefab prefabname parm=value .. [-options]
.. OR ..
pl scriptfile [-options]

Description

pl is the primary component of the 'ploticus' data display package

pl is a program that produces plots and charts from data, and produces results that can be viewed on web pages, paper, slides,or interactively on the screen. Standard types of plots may bedone using prefab plot templates, or a user-developed script filemay be supplied for greater flexibility and customization.pl may be executed from the command line or as a CGI program.

For complete online docs and downloads see http://ploticus.sourceforge.net

Where to find examples

See the various prefab examples .A large number of script examplesare also available.Some usage examplesare also shown below.

Command line arguments

Command line arguments may generally be given in any order.If there are arguments that you want to always have in effect, you can invoke them from a config file.Many settings can also be made dynamically from scripts via proc settingsor proc page.Processing occurs in this order: first the config file is read; then command line args are processed (left to right); then proc pageand/or proc settings.Later settings override earlier ones.

Basic command line options

-prefab prefabname

: Produce a plot using a prefabplot template.prefabname identifies the template, eg.cron or vbars.Necessary parameters are supplied on the command line using the form parm=value.

scriptfile
-f scriptfile

names a script filethat will be interpreted to produce results.Alternatively, -stdin may be used to indicatethat script will be available on standard input.

variable=value

Declares the namedvariable and sets it to the given value. This is a convenient way to pass informationto prefabs and scripts. Variable names are case-sensitive.
Example: CUTDATE=10-31-98
sets the variable CUTDATE to 10-31-98.

-o outfile | stdout

Specify a filename where the result will be written.No processing is applied to this name.. so the ending should be appropriate forthe selected output format, eg. use .png for PNG files.If -o stdout is used,result will be sent to standard output. If -o is not specified, a default output filenamewill be used.
Example: -o fp001.png

-dir dirname

Set ploticus' working directory to dirname.If used, this argument should be specified leftmost on the command line, since it affects evaluation of other args.

Result format options

(Availability depends on your ploticus configuration/build)

-png PNG image

-gif pseudo-GIF image

-jpegJPEG image

-svg or -svgz SVGgraphic. See also SVG / XML options below.

-swf SWF(flash) result.

-wbmpWBMP image

-eps EPS (encapsulated PostScript)

-ps paginated PostScript to stdout

-x11 display on X11 screen

-drawdumpfilenameproduce no visible graphic; save a generic representation of the graphic result to a file.By using -drawdump and -drawdumpa you can easily overlay or combine results from separate pl runs.The drawdump file can be rendered later in any desired format, using this command:pl -prefab draw dumpfile=filename or by using proc drawcommands.Drawdump capability is available in all builds. (2.30+)

-drawdumpafilenamesame as -drawdump but result is appended to file.

Clickable image maps and mouseover options

-csmap

: produce a client-side clickable imagemapto accompany a png, gif, or jpeg.These can be used for hyperlinks, and also for providingpop-up text labels that appear when the mouse passes over a region.By default, client-side map content is written to stdout.

-map

produce a server-side clickable imagemap fileto accompany a png, gif, jpeg, or SVG.

-csmapdemo

: Same as -csmap but all mapped regions are shown outlined in green,and a complete HTML chunk is produced which involves the output image name.

-mapdemo

Same as -map but all mapped regions are shown outlined in green.

-mapfile filename | stdout | stderr

explicitly name the output file containing the map info. The name may also be set in proc page.If a name is not specified, client-side image map info will be written to stdout;server-side image map info will be written to a file having the same name as the output result fileexcept with a .map suffix(stdout may be useful in dynamic content HTML situations).For SVG this parameter is not needed, since image map info is embedded in the SVG file.

Result sizing options

-scale sx[,sy]

Scale the final result.If one value is given, the result is scaled by this amount in both x and y.If two values are given, scaling in x and scaling in y may be done independently.A scale value of less than 1.0 reduces thesize; an scale value of greater than 1.0 enlarges. Scaling is done relative to the origin (0,0) which is at the lower left.
Example: -scale 0.7

-pagesize width,height

Sets the pre-crop size of the result image for GIF/PNG/JPEG, or sets the display window size when drawing to X11. On other output devices this option does nothing.width and height are in absolute units.0,0 is the lower left corner.If -pagesize is not specified, the default size will be 8" x 8".Size is set before any drawing takes place and is unaffected by the -scale option.

When rendering PNG/GIF/JPEG images, this option determines amount of internal memory allocation for accommodating the image.The result can never be bigger than this size, and any drawing outsize the bounds will not be visible.To create PNG/GIF/JPEG images larger than 8" x 8", this option MUST be specified to set a bigger size.Cropping options (below) can be used along with -pagesize as long as they result in a smaller rectanglethan the pagesize; they take effect after all drawing has been completed.

-pagesize has no effect with EPS or paginated PostScript results (the PostScriptBoundingBox will be determined by the extent of the graphic).

Example: -pagesize 7,3

-tightcrop

For image or EPS output, crop the result tightly to the extent ofthe design. Normally a small margin is allowed on all four sides.This option sometimes crops a bit too tight; if so try -croprel.

-crop x1,y1,x2,y2

Crop image or EPS result to the box specified byx1,y1 and x2,y2, in absolute units.

Note that there may be no spaces in the coordinates specification.Cropping takes place after design is rendered and does notaffect coordinate locations.
Example: -crop 1.2,0.8,4.4,5.2

-croprel left,bottom,right,top

Crop image or EPS result tightly to the extent of the design (like -tightcrop),but then adjust the cropping outward or inward on one or more sides.left is the amount to adjust the left side, in absolute units.Similarly for bottom, right, and top.Positive values always adjust outward from center; negative values adjust inward (tighter).There may be no spaces in the left,bottom,right,top specification.Cropping takes place after design is rendered and does notaffect coordinate locations.
Example: -croprel 0,-0.1,0,0.1

Graphics environment options

-font font

sets the overall font to font. See fontsfor more info.

-textsize pointsize

sets the overall default textsize to pointsize.All embedded size specifications will be rendered relative to this.

-linewidth w

: sets the overall default linewidth to w.All embedded line width specifications will be rendered relative to this.See linedetails(pli) for more on line width.

-color color

sets the overall default text and line drawing color to color.

-backcolor color

sets the background color to color.

-cm

Use centimeters as your absolute units, instead of inches.On the command line this must appear to the left of any arguments dealing withabsolute unit values, such as -pagesize.Centimeter absolute units can also be set via proc settings.If cm will always be the desiredabsolute units, the preferred way to achieve this is by using units: cm in a ploticus config file.

-inches

Use inches as your absolute units. This is the default.

-outlabel label

Set the label or title for the output. For X11 this sets the window title;for PostScript and SVG it sets the %%Title attribute.

Capacity setting options

These options (new with version 2.10) allow capacities to be raised for accomodation of very large data sets, or lowered to minimize memory usage.The defaults in this section are defined in pl.h.

-maxrows nrows

Set the capacity for data rows to nrows. Default nrows is 10,000.Ploticus will allocate one pointer for each row.

-maxfields nfields

Set the capacity for data fields to nfields. Default nfields is 200,000.Ploticus will allocate one pointer for each field.

-maxproclines nlines

Set the capacity for script lines for active procs to nlines.Default nlines is 5000.Active procs are the current proc, all #saved procs, andall proc getdata procs that contain embedded data.Ploticus will allocate one pointer for each line in each active proc.

-maxvector ncells

: Set the capacity for the data plotting vector to ncells.Default ncells is 100,000.The data plotting vector is an array which holds plottablevalues for situations where the values must be sorted or pre-screened forbad values. Ploticus will allocate one double value for each cell.

-maxdrawpointsn

: Use this if you need to render a polygon having more than 500 points in PNG/GIF/JPEG, X11, or SWF, orany continuous line having more than 500 points in SWF.

Note: raising the maximum number of categories may be done using proc categoriesfrom within the script.

SVG / XML options:

-svg_tagparms string

This allows arbitrary text to be inserted into the opening <svg> tag.
Example: -svg_tagparms 'height="10cm" width="15cm"'

-omit_xml_declaration

By default the first line of the SVG result will be the XML declaration <?xml .. > .Use this option to suppress the XML declaration line ifthe SVG result is to be embedded into a larger XML document.

-xml_encoding method

Set the XML character encoding method. This encoding will be indicated in the XML declaration line.The default is iso-8859-1 which provides Latin and Western European character sets.For Unicode fonts this should be set to utf-8 (for more discussion see the Unicode section in fonts).

-tag

Causes a suitableHTML <EMBED> tag to be written to standard output.

-zlevel n

This may be used to set the compression level to n for SVGZ output(0 - 9 where 9 is highest level of compression and the default).

Interactive (workstation) use options

-winloc x,y

Control where on the screen the upper-left corner of the X11 displaywindow will be placed. x and y are in pixels.Example: -winloc 200 0

-v command
-viewer command

After generating results in the specified format, execute commandin order to view the results on your screen. The output file will automatically beincluded in the command. For example, if a GIF file is beinggenerated you might use this to invoke the xv utility: -viewer xv. If PostScript is being generated you could use something like this toinvoke the ghostview utility: -viewer "gv -magstep -1".The given command must be available on your system and locatable inyour command search path.This option may not be used with -o stdout.

-noshell

If specified, ploticus is prohibited from issuing any shell commands.This is a security feature useful for example when running a script thatwas sent to you by an unknown party. New in 2.31

Paper orientation options

-landscape

For paginated postscript, set paper orientation to landscape (oblong).

-portrait

For paginated postscript, set paper orientation to portrait.

-posteroffset x,y

Allows production of large-size posters made up of multiple standardsheets of paper butted together. May be used only with paginated PostScript,and should be used in combination with the -scale and -textsizeoptions. x,y is the point within your result (in absolute units) that is to be placed at the lower left corner of the page.For further discussion of this, see posters .

Development and debugging options

-debug

: Debug mode. Causes dianostic information to be written to the diagnostic stream (stderr by default, see -diagfile below).Highly recommended if you are experiencing difficulty.Best to use -debug as the first (leftmost) argument so that it can reporton all arguments gotten.Another effect of debug mode is that any temporary files are not removed upon termination.

-ping

Write the ploticus name and version number to standard output and exit. versions 2.33+

-echo [ diag | stdout]

Write ploticus script lines as they are executed. Lines are written to the diagnostic stream (standard error by default) or standard output.Lines are written after variablesand most script directives, including flow-of-control directives, are evaluated.

-showbad

Identify unplottable data, showing the value, and its row and field.

-diagfile filename | stderr | stdout

All non-error messages and output will be written to this file (default is stderr).

-errmsgpretag

Allows developer to set the first portion of all ploticus error messages to tagfor purposes of presentation or identification.

-errfile filename | stderr | stdout

All error messages will be written to this file (default is stderr).

-help or -? or -version

Print version number, copyright info, web site address, etc.

Output file names

The output file may be specified on the command line using the -o option,or via Proc Page's outfilename attribute.If so, the result is written to a file of that name.-o stdout may also be used to send result to standard output.

Otherwise, if your script filename has a "recognized extension"( .p, .pl, .plo, .pls, .htm or .html ),the base part of the script file name is used and .png, .gif, etc.is appended. If your script filename doesn't have a recognized extension, the generic name out.* will be used.

X11 output is always displayed on the screen, andpaginated PostScript is written to standard output unless -o is used.

If page breaks (Proc Page) are encountered when rendering in any format otherthan paginated PostScript,special action is necessary since each page must go into a separate file. A Proc Page outfilename may be specified for each page;otherwise a pn prefix will be attached to the beginning ofeach page's output file name to indicate page n.

If a clickmapis being generated, the result file is named similarly to the above.

Usage examples

The following example uses the scat prefab:

: pl -prefab scat -png datafile=results.dat x=2 y=3

The following examples assumethat you have a script file called lineplot1.p.

: pl -x lineplot1.p = view on X11 screen
: pl -png lineplot1.p = create PNG image lineplot1.png
: pl -gif lineplot1.p -o stdout = create GIF image on standard output
: pl -gif lineplot1.p -viewer xv = produce GIF and view using xv (assuming xv image viewer is available on your system).
: pl -eps lineplot1.p = produce EPS file lineplot1.eps
: pl -eps lineplot1.p -viewer gv = produce EPS and view using gv (that's ghostview, assuming it is available on your system).
: pl -eps lineplot1.p -o lineplot.eps = produce EPS into file lineplot.eps
: pl -ps lineplot1.p | lp = produce paginated postscript and send tounix lp print spooler.
: pl -ps lineplot1.p -veiwer gv = produce paginated postscriptand view using ghostview.

Environment

PLOTICUS_CONFIG

: The name of a ploticus configuation file, for setting default date notations, numbernotations, measurement units, etc.

PLOTICUS_PREFABS

: The path name of a directory where ploticus will look for prefabscripts. The "factory" prefabs are located in the ploticus ./prefabs subdirectory.

LC_CTYPE, LC_COLLATE, LANG

Locale support. Thanks to Oleg Bartunov olegAATTsai.msu.sufor contributing this. pl must be built with -DLOCALE for this to work.

TDH_ERRMODE

Control the disposition of error messages. Allowable values: stderrwhich is the default, and cgi which causes error messages to be written to stdout with html formatting.

Bugs

Ploticus has some stated limitations(mostly related to capacities that you may run into if you're dealing with large data sets). To report problems or get help see the ploticus support page.

Author, Copyright, Licensing

The primary author is Stephen C. Grubb.Ploticus covered by the General Public License (GPL)... please see the ploticus copyright pagefor more info.

Index

Name
Synopsis
Description
Where to find examples
Command line arguments
Basic command line options
Result format options
Clickable image maps and mouseover options
Result sizing options
Graphics environment options
Capacity setting options
SVG / XML options:
Interactive (workstation) use options
Paper orientation options
Development and debugging options
Output file names
Usage examples
Environment
Bugs
Author, Copyright, Licensing
See also

This document was created byman2html,using the manual pages.