Help for PLOT3D

PURPOSE

    "plot3d" plots 3-D IBIS graphics-1 files in true 2-D perspective
using the gnuplot plotting software. 


PLOT OUTPUTS

    The other type of output come from the PLOT and PLOTFMT parameters.
PLOT allows the user to display data from 5 areas on the CCD on an x,y
plot using the gnuplot package after exiting the program. PLOT produces
a file of gnuplot commands contained in a file having a .gpi file extension.
Another file with an .asc extension is create containing columns of data
that are displayed by the gpi file.

   The PLOTFMT parameter allows the user to generate a postscript file of
the output for use in documentation by choosing PLOTFMT=EPS. The default
is to generate a gnuplot interactive display.


  PLOT NAMING CONVENTIONS

  The user should enter only the parent file name without an extension
  for the PLOTOUT parameter.  The program will supply the extensions.

  For example, if the user has an input file of indata.dat and  PLOTOUT=outplot
  then for the interactive plot the following files are produced:

     outplot.gpi
     indata.dat.asc

  The first file is the gnuplot instruction file and the second is the
  data file used by gnuplot.

  If the user wanted an encapsulate postscript file with PLOTFMT=eps
  then the following files are produced:

     outplot.eps.gpi
     indata.dat.asc

  Remember entering the following command gives the eps file, outplot.eps

  ush gnuplot outplot.eps.gpi

  If you move the gpi file to another directory, you must also move the
  input data file, indata.dat.asc to the same directory.

  Note that the gpi file produced by this program has the name of the
  input file embedded in the plot command inside the gpi file, e.g..
  plot  'indata.dat.asc' u  1: 9 t .......


USING GNUPLOT


  INTERACTIVE:

    This program uses the gnuplot package for its plots. Gnuplot is a
  separate package from Vicar and is not actually invoked inside this
  program.  Instead this program creates a template of gnuplot commands
  which are written out as a separate file. The plot is then viewed after
  exiting this program. The file has the extension .gpi. You view
  the plot by issuing the following command in the vicar shell.

  ush gnuplot output.gpi

  or external to vicar as

  gnuplot output.gpi

   After viewing the data, you close the plot by clicking the mouse anywhere
  except on the top bar of the plot. Clicking on the top bar allows you
  to move the plot to any convenient place on the terminal screen.  (While
  the plot is displayed you cannot enter any commands to the vicar shell).

  The data to be plotted by gnuplot is read from a separate file, created
  by this program, which contains columns of data in ascii text.
  File naming conventions are discussed in the OUTPUT section, but in this
  case that file extension will be .asc.

  It is possible to keep the plot alive for comparison purposes by issuing
  the following command.

  ush gnuplot --persist output.gpi
  (You will be able to enter commamds to the vicar shell after clicking on
  the mouse on the plot).


  HARDCOPY:

  This program also allows you to create a hardcopy encapsulated postscript
  plot suitable for publications. This file can be viewed with ghostscript
  or gimp. The encapsulated postscript file is not created by this program
  by by the gnuplot program from a gpi file made especially for this purpose.
  this file has the extension, eps.gpi. You create the hardcopy plot via
  the following command

  ush gnuplot output.eps.gpi

  This creates the eps file output.eps. You can view this file by

  ush gimp output.eps

   2-D PERSPECTIVE PLOTS OF 3-D DATA

   The previous plotting package required the user to input the
   perspective viewing angles and distance, ELEV, AZIMUTH and DISTANCE.
   The viewing angles are with repect to an observer at some
   DISTANCE looking back toward the coordinate system origin.
   These angles are the trig complement of the coordinate system
   angles, phi (ELEV) and theta (AZIMUTH). Phi is the angle above
   or below X-Y plane and theta the angle clockwise from Y axis
   (usually called North in mapping systems).

   If the chosen perspective wasn't pleasing then the user kept
   entering appropriate angles or distance until it became so.

   Gnuplot does not have this limitation. If you plot a 3-D data
   set the user can rotate the viewing angles or change distances
   with appropriate mouse commands on the plot panel. The lower 
   left hand portion of the plot panel is updated with the new 
   angles and position:

   
   view:  elev,  azimuth   scale: 1.0000  1.0000

   The scale values are the scale of the X-Y plane and the Z-axis.

   The original angles and distances are in the title of the
   plot.
 
   When you have the desirable view then there is a problem
   with saving the plot that didn't exist with the old xrt
   plotting package. The updated angles and distance are
   not available to vicar.

   The purpose of plot3d originally was to create a 3-D object
   in an IBIS-1 graphics file, then find a perspective and then
   convert that graphics file into a new graphics file. The
   older program had all the mathematical operations to do that
   perspective rendering that is part of gnuplot.

   So plot3d cannot do that function. 

   A new program perspec was created for that purpose.

   Once you have chosen the desired view you must record the
   four values at the bottom of the plot panel and enter them
   into program perspect using the input file as for plot3d. This
   will create the output perspective that formerly was done
   by the old plot3d program.

   The vicar program pltgraf is and alternate way to view the
   IBIS-1 graphics format. 

    DEVELOPER Note:

    This program used to link to the XRT plot library -lxrt. Calls to
  that library were mitigated through a Calcomp conversion library,
  xrtps located in the p2 subroutine library. With the conversion to
  gnuplot, neither of these packages are used.


EXECUTION

Examples:

A standard autoscaling 3-D plot:
plot3d  THREE.GRA  PLOTSIZE=6.0 ELEV=30 AZIMUTH=135 DISTANCE=200 

To plot a file in (line,sample,Z) format and scale the Z value down:
plot3d  THREE.GRA  DATAFORM=LSZ PLOTSIZE=3 ZSCALE=100

To plot a 3-D axis and title:
plot3d  THREE.GRA  PLOTSIZE=6.0 ELEV=30 AZIMUTH=135  AXIS=10  			'NOBOX TITLE='THREE D PLOT'

For manual scaling:
plot3d  THREE.GRA  SCALE=10 PLOTOFFS=(4.5,6)

For 2-D file output:
plot3d  THREE.GRA  TWO.GRA  ZSCALE=10  ORIGIN=(100,100,10)

For the default plot:
plot3d  THREE.GRA  



Original Programmer:	Frank Evans	January 1987

Cognizant Programmer:	Michael Tschudi	June 1987

Revision History:

    10-July-95 - Randy Schenk (CRI) - Ported to Unix
     7 Feb 2013 - Ray Bambery - Updated to Linux 64-bit, gnuplot
    13 Feb 2013 - Ray Bambery - Updated documentation 
    10 Jul 2013 - Ray Bambery - Consistent file naming conventions
    13 Jul 2013 - Ray Bambery - Adjusted eps format to more readable fonts
                                Remove vestiges of debug statements

PARAMETERS: