----- file created by makedoc on: Thu Nov  5 15:14:57 2009
----- Documentation for /scisoft/xop2.3/extensions/shadowvui/src/lib/plotxy.pro -----

 NAME:
	PLOTXY
 PURPOSE:
	an IDL implementation of the PLOTXY SHADOW's utility
 CATEGORY:
	SHADOW's utilities.
 CALLING SEQUENCE:
	plotxy,shadow_in,col1,col2,shadow_out,keyword_parameters
 INPUTS:
	Number of input variables can be from one to four:
	When using one input, it should be an array of points with two
	  columns (i.e. dblarr(2,npoints). The first column contains X
	  coordinates and the second column the Y values.
	When using two inputs, the first one is the array for X and the
	  second one for the Y.
	With three inputs [usual case]:
	shadow_in   may be:
           a shadow file (between quotes) (e.g. 'begin.dat') or
           an IDL-SHADOW structure
	col1    x column to plot
	col2    y column to plot
           the colum meaning is the following:
           1   X spatial coordinate [user's unit]
           2   Y spatial coordinate [user's unit]
           3   Z spatial coordinate [user's unit]
           4   X' direction or divergence [rads]
           5   Y' direction or divergence [rads]
           6   Z' direction or divergence [rads]
           7   X component of the electromagnetic vector (s-polariz)
           8   Y component of the electromagnetic vector (s-polariz)
           9   Z component of the electromagnetic vector (s-polariz)
          10   Lost ray flag
          11   Energy [eV]
          12   Ray index
          13   Optical path length
          14   Phase (s-polarization)
          15   Phase (p-polarization)
          16   X component of the electromagnetic vector (p-polariz)
          17   Y component of the electromagnetic vector (p-polariz)
          18   Z component of the electromagnetic vector (p-polariz)
          19   Wavelength [A]
          20   R= SQRT(X^2+Y^2+Z^2)
          21   angle from Y axis
          22   the magnituse of the Electromagnetic vector
          23   |E|^2 (total intensity)
          24   total intensity for s-polarization
          25   total intensity for p-polarization
          26   K = 2 pi / lambda [A^-1]
          27   K = 2 pi / lambda * col4 [A^-1]
          28   K = 2 pi / lambda * col5 [A^-1]
          29   K = 2 pi / lambda * col6 [A^-1]
          30   S0-stokes = |Es|^2 + |Ep|^2
          31   S1-stokes = |Es|^2 - |Ep|^2
          32   S2-stokes = 2 |Es| |Ep| cos(phase_s-phase_p)
          33   S3-stokes = 2 |Es| |Ep| sin(phase_s-phase_p)
	When four inputs are given, the fourth is optional:
 OPTIONAL INPUT PARAMETERS:
        shadow_out = name of IDL-SHADOW structure where store the file
 KEYWORD PARAMETERS (INPUT):
        XRANGE = [ min_x,max_x ]
        YRANGE = [ min_y,max_y ]
        XYRANGE = [ min,max ] (sets XRANGE=YRANGE)
        NOLOST = consider losses
            0 all rays (default option)
            1 exclude losses;
            2 only losses;
        NBINS = number of bins (def=25);
        CART = boolean when if present and non-zero
               forces the data space to have cartesian coordinates
               (i.e. square has aspect ratio one)
        NOCOMM =  0 with comment section (default)
                  1 without comment section 
        HISTO  = -1 skip histograms
                  0 with histograms (default)
                  1 overplot histogram weigthed with intensity
                  2 plot only histograms weigthed with intensity
		   3 (same as -1)
        TITLE  = chain for title	
        SLIT   = [ lb_x,lb_y,ru_x,ru_y ] where 
                     lb_x and lb_y  are the coordinates of the
                     left bottom vertex of the slit and
                     ru_x and ru_y are the coordinates of the 
                     right upper vertex of the slit
		IF lb_x=ru_x and lb_y=lb_y and GETFWHM keyword is set,
               then the overploted slit is lb_x times the horizontal 
               fwhm and lb_y times the vertical one. 
	GAUSSFIT = makes a gaussian fit of the histo
		0  No (default)
		1  Gauss+2nd degree polynomial (using gauss_fit routine)
		2  Gaussian: using (fit_voigt(...,/Gaussian) routine)
		3  PseudoVoigt: using (fit_voigt() routine)
		4  Lorentzian: using (fit_voigt(...,/Lorentzian) routine)
                       publication, i.e. username, date, time, filepath, etc.
                       When flag is present and non-zero, output is supressed.
        PUBLISH = flag to supress graphic output not suitable for
        CONTOUR =  0 (default) no contour (scattered plot)
		    1  makes contour curves (no reflectivity considered)
		    2  makes contour curvex including reflectivity
		    -1 or -2 same as 1 and 2 (respectively) but 
			using colored polycontours.
		    3 (same as -1)
		    4 (same as -2)
		    5 Pixelized contour (no reflectivity considered)
		    6 Pixelized contour including reflectivity
		    Nota Bene: when using contours, any keyword accepted
		    by the IDL "contour" routine is accepted by plotxy and 
		    passed to contour.

	 CALFWHM  = 1 : calculates the fwhm values of the histograms
	            2 : calculates the fwhm values of the histograms and 
			overplots a slit with these values.
	 INFOSH = when set to 1, calls also the INFOSH procedure.
	 NOERASE = when set to 1, noerase the previous plot. Many plotxy
		plots can be combined in one page by using the 
		!p.position value and the /noerase keyword.
	 CHARSIZE = starting character dimension
	 MULFAC = A multiplicative factor to change the X and Y scales.
		Set to a scalar for applying both H and V scales, or
		to [Mx,My] to apply independently H and V scales.
        GROUP The parent id for the caller widget (used to positioning
               error and information windows).
	RETRACE Set this keyword to a distance for retracing (in vacuum) 
		the shadow file before to be plotted. Only applied if
		the input is a shadow file or structure.
	POSITION A four element arrays [x0,y0,x1,y1] defining the 
		position of the plot (as in !p.position)
	WEIGTH An array of weight (if inputs are arrays)
	XPLOT Set this keyword to -1 for launching an xplot window with
             the plotted points. Set this keyword to the xplot window
             identifier to send data to an existing xplot window. 
       NSPLIT, set this keyword to an integer > 1 to calculate errors
             in intensity value and fwhm by splitting the ray block in
              NSPLIT groups. 

 CONTOUR KEYWORD PARAMETERS:
        SMOOTH =  to smooth the contour plot graphic. It smooths the
		3D histogram with the data to be display by using the
		IDL's smooth founction with width equal to the smooth value.
	 NC_BINS the number of bins used for calculating the 2D histogram
		in the case of CONTOUR (Default: NC_BINS=NBINS). 
		It may be a scalar (used for both X and Y) or a 2-elements 
		array [Nx,Ny].
	 NLEVELS = When contour is selected, nlevels indicates the
		  number of contour levels (Default = 6)

 COLOR KEYWORD PARAMETERS:
        CCOL = Column by which to color code scatter plot points.
               If this parameter is present and non-zero, each point
               will be plotted with a color which depends on the
               value in the column specified and the current color
               table.  If the parameter is an integer, it is interpreted
               as the column number of the data to use for color information.
               If the parameter is an array, it is interpreted as the actual
               data by which to color the rays.
        CARRAY = An array with the numerical values of the for the
		color column (used insted the CCOL xolumn in the file). When 
		this keyword is set, the CCOL keyword is irrelevant.
        CLIMITS = [min,max], the limits applied to the values in the
               color information column, the default is to use the
               range of the data in that column.
        CBINS   =   number of bins for the color histogram (defaut=100)
        CREF    =   when set to 1 takes into account reflectivity
                    in the color histogram (Default=0, no reflectivity)
        CFILE   =   name of the shadow file or IDL-SHADOW structure
                    from where the color column is read. To be set when
                    the file is different from the shadow_in.

 KEYWORD PARAMETERS (OUTPUT):
 	 FWHM_VAL = IF CALFWHM is set, fwhm_val stores the FWHM value of 
		  the histogram in an IDL variable dblarr(2) with the 
                 values for the horizontal and vertical histograms 
                 respectively.
 	 FWHM_MEAN = IF CALFWHM and NSPLIT are set, fwhm_mean stores 
                 the FWHM mean value (one standard deviation) of 
		  the histogram in an IDL variable dblarr(2).
 	 FWHM_ERROR = IF CALFWHM and NSPLIT are set, fwhm_error stores 
                 the FWHM error value (one standard deviation) of 
		  the histogram in an IDL variable dblarr(2).
	 FWHM_FIT = IF CALFWHM is set, fwhm_fit stores the FWHM value of 
                 the gauss fit in an IDL varianle
	 EXTRACT = extract stores the data plotted (scattered points) in
	           an IDL variable ftarr(2,n_points_good)
	 C_DATA = If CONTOUR is set, set this keyword to a named variable 
               to retrieve the 2D histogram used for contours.
		It returns a structure {x:x, y:y, z:z} containing
		the surface (z tag) and two arrays with the x and y arrays.
               This option permits you the to reuse of the contours
		generated for further manipulation, e.g. 
		IDL> contour,c_data.z,c_data.x,c_data.y

 OUTPUTS:
	a graphic. It may also create an IDL-SHADOW structure (optional)
 COMMON BLOCKS:
	None.
 SIDE EFFECTS:
	None.
 RESTRICTIONS:
	It may be conflict between CART axis and CONTOUR. To check!!
 PROCEDURE:
	Similar to SHADOW's original.
 KNOWN BUGS:
 MODIFICATION HISTORY:
	M. Sanchez del Rio. ESRF. Grenoble, May 1991
       91-12-11 MSR includes SLIT, GAUSSFIT and XYRANGE options.
       92-07-10 MSR includes INPUT_TYPE option
       92-07-14 S. Turner apply WHERE routine to eliminate loop
                for plotting only good rays.  Also change position parameters
                to put axes labels back on the plot.
       7-15-92  SWT adds color to plot, ccol selects colorization,
                and indicates which column to use.
       7-16-92  SWT automates the selection of the input type,
                parameter INPUT_TYPE is no longer needed.
       7-16-92  SWT includes an option to have cartesian coords for plot.
       7-20-92  SWT provides option of color-coding points from
                a different ray file, also makes font size for annotation
                scale with plot size for all devices, notably 'ps',
                which previously did not work.
       92-09-02 MSR includes columns > 18
       92-09-03 MSR includes CREF, CFILE, and few modifications
       92-10-02 MSR adds GETPHASE to correct phases for stokes parameters
       92-10-02 MSR adds option 2 to NOLOST
       92-12-04 MSR adds option 2 to HISTO
       93-04-05 MSR adds NLEVELS, and color contours plots
       93-04-19 MSR changes GAUSSFIT by GAUSS_FIT
       93-05-14 MSR allows either GAUSS_FIT or GAUSSFIT
       93-07-08 MSR includes printing the intensity and command
	93-10-21 MSR adds CALFWHM,FWHM_FIT and FWHM_VAL keywords to 
		 extract values from histograms.
	93-10-26 MSR adds  EXTRACT keyword
	93-11-03 MSR fix a bug in colored contours
	94-09-27 MSR makes to print the FWHM in the screen when /CALFWHM is set
	95-02-10 MSR adds the infosh keyword
	95-06-09 MSR clean-up by using getshcol function. Adds /noerase
		 and allow multiple plots in one page by using the
		 !p.position system variable. Cosmetics.
	95-06-14 MSR for contours: removes the /spline and add smooth kw.
		Short code by using histosh... Other small changes.
	95-09-25 MSR  fix bug in /cart option. Adds CHARSIZE kw.
	96-01-30 MSR  fix bug in number of lost rays when /nolost is not used.
		      Fix bug in limits when contour is set.
	96-05-03 MSR  Add keyword NFILES to be passed to READSH
	96-08-20 MSR  Add keyword MULFAC
	97-12-05 srio@esrf.fr duplicates the negative keyword values (to
			be used with the interface xsh_plotxy) and uses catch.
	98-01-07 srio@esrf.fr adds the possibility to input two arrays
			and adds CARRAY keyword.
	98-03-10 srio@esrf.fr adds Dialog_Message in catch section.
	98-04-07 srio@esrf.fr uses column_name do display it.  Cosmetics.
	98-04-07 srio@esrf.fr adds _EXTRA and C_DATA keywords
	98-07-10 srio@esrf.fr adds NC_BINS kw.
	00-03-27 srio@esrf.fr changed !d.n_colors -> (!d.n_colors<255)
	06-02-16 srio@esrf.fr added the RETRACE keyword
	06-02-21 srio@esrf.fr added pseudovoigt fit to histograms. 
		Rearranges mulfac
	16-10-06 srio@esrf.fr changes fitting routines. Added lorentzian
			Added weight kw. 
	11-06-07 srio@esrf.eu Added pixelized contours. 
	25-06-07 srio@esrf.eu Makes 2D histograms using hist_nd2
	15-04-08 srio@esrf.eu Adjust comments box... Added xplot kw.
	2008-09-09 srio@esrf.eu sort the code for making the main plot
		at the end, for allowing cursor display and zoom.
	2009-01-12 srio@esrf.eu added NSPLIT keyword to make statistics.
	2009-03-03 srio@esrf.eu added CALFWHM=2 and calculate intensity
		in slits.
 

