Provided by: ploticus_2.42-4.2_amd64 bug

Name

       ploticus - data display package

Synopsis

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

Description

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

       ploticus  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 be done using  prefab plot templates , or a user-developed  script file may
       be supplied for greater flexibility and customization.  ploticus 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 examples are also
       available.  Some  usage examples are 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 settings or   proc  page.   Processing
       occurs  in this order: first the config file is read; then command line args are processed
       (left to right); then  proc page and/or  proc settings.  Later settings  override  earlier
       ones.

Basic command line options

       -prefab prefabname

              Produce  a plot using a  prefab plot 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 file that will be interpreted to produce results.  Alternatively,
              -stdin may be used to indicate that script will be available on standard input.

       variable=value

              Declares the named variable and sets it to the given value.  This is  a  convenient
              way to pass information to 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 for the 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 filename will 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

       -jpeg JPEG image

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

       -swf  SWF (flash) result.

       -wbmp WBMP image

       -eps EPS (encapsulated PostScript)

       -ps paginated PostScript to stdout

       -x11 display on X11 screen

       -drawdump  filename  produce  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 ploticus runs.  The drawdump file can be rendered later in
       any desired format, using this command: ploticus  -prefab  draw  dumpfile=filename  or  by
       using  proc drawcommands.  Drawdump capability is available in all builds. (2.30+)

       -drawdumpa filename same as -drawdump but result is appended to file.

Clickable image maps and mouseover options

       -csmap

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

       -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.

       -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;  For SVG this parameter is not needed, since image map info is
              embedded in the SVG file.

       -map

              produce a  server-side clickable imagemap file to accompany a png,  gif,  jpeg,  or
              SVG.  Note: server-side maps are deprecated.

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 the size; 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 rectangle than the pagesize; they take  effect  after  all
              drawing has been completed.

              -pagesize  has  no  effect with EPS or paginated PostScript results (the PostScript
              BoundingBox 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  of  the  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 by  x1,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 not affect 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 not affect
              coordinate locations.
              Example: -croprel 0,-0.1,0,0.1

       -pixsize width,height

              If specified, result PNG/GIF/JPG image will be created at exactly  this  width  and
              height  in  pixels.   Does  not  interact  with  scaling  or  cropping...  user  is
              responsible for ensuring that content fits appropriately into the  specified  size.
              User  is  also  responsible  for setting -pagesize appropriately for larger images.
              New in 2.40

Graphics environment options

       -font font

              sets the overall font to font.  See  fonts for 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 with absolute unit values,
              such as -pagesize.  Centimeter absolute units can also be set via   proc  settings.
              If  cm will always be the desired absolute 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, and  all  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 plottable values for
              situations where the  values  must  be  sorted  or  pre-screened  for  bad  values.
              Ploticus will allocate one double value for each cell.

       -maxdrawpoints n

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

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

       -cpulimit #Include nbsp2 s

              Set unix resource limit on cpu time to s seconds.  Default is 30 seconds.   New  in
              2.40

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 if the 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 suitable HTML <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 display window 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 command in order to  view
              the  results on your screen.  The output file will automatically be included in the
              command.  For example, if a GIF file is being  generated  you  might  use  this  to
              invoke  the xv utility: -viewer xv.  If PostScript is being generated you could use
              something like this to invoke the ghostview utility: -viewer "gv -magstep -1".  The
              given command must be available on your system and locatable in your 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 that was 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  standard  sheets  of
              paper  butted  together.  May be used only with paginated PostScript, and should be
              used in combination with the -scale and -textsize options.  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 report on 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  variables  and  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).

       -errmsgpre tag

              Allows developer to set the first portion of all ploticus error messages to tag for
              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,  and  paginated  PostScript  is  written  to
       standard output unless -o is used.

       If  page  breaks  (Proc  Page)  are  encountered  when  rendering in any format other than
       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 of each page's output file name to indicate page n.

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

Usage examples

       The following example uses the  scat prefab:

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

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

               ploticus -x lineplot1.p = view on X11 screen

               ploticus -png lineplot1.p = create PNG image lineplot1.png

               ploticus -gif lineplot1.p -o stdout = create GIF image on standard output

               ploticus -gif lineplot1.p -viewer xv = produce GIF and view using xv (assuming  xv
              image viewer is available on your system).

               ploticus -eps lineplot1.p = produce EPS file lineplot1.eps

               ploticus  -eps  lineplot1.p  -viewer  gv  =  produce EPS and view using gv (that's
              ghostview, assuming it is available on your system).

               ploticus -eps lineplot1.p -o lineplot.eps = produce EPS into file lineplot.eps

               ploticus -ps lineplot1.p | lp = produce paginated postscript and send to  unix  lp
              print spooler.

               ploticus  -ps lineplot1.p -veiwer gv = produce paginated postscript and view using
              ghostview.

Environment

       PLOTICUS_CONFIG

              The name of a  ploticus configuration file , for setting  default  date  notations,
              number notations, measurement units, etc.

       PLOTICUS_PREFABS

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

       LC_CTYPE, LC_COLLATE, LANG

              Locale support.  Thanks to Oleg Bartunov  oleg@sai.msu.su  for  contributing  this.
              ploticus must be built with -DLOCALE for this to work.

       TDH_ERRMODE

              Control  the  disposition of error messages.  Allowable values: stderr which 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 page for more info.

See also

        http://ploticus.sourceforge.net

                         11-MAR-2009   PLOTICUS ploticus.sourceforge.net              ploticus(1)