Extended IDL Help

  • Return to IDL Topics

    Last modified: Tue Aug 7 08:53:43 2007.


    List of Routines


    Routine Descriptions

    ADDFR

    [Next Routine] [List of Routines]
     NAME:
           ADDFR
    
     PURPOSE:
           Add the frames in a CR-39 digitized image.
           Input structure must be single block, 3 dimensions.
           Output structure will be 2 dimensions.
    
     CATEGORY:
           Math 
    
     CALLING SEQUENCE:
           STR_Total = ADDFR(STR_IN, /ALLFRAMES)
           STR_Total = ADDFR(STR_IN, FRAMES)
           STR_Total = ADDFR(STR_IN, FRAMES [, NFRAMES])
    
     Where:
           STR_Total - Composite image equal to the sum of the designated frames
           STR_IN    - Structure or structure array number with the CR-39 images.
                       This may be any 3 dimensional, single block structure
           ALLFRAMES - If set, frames 1 to 19 will be added.  If the number of 
                       frames (size of dimension 3) is not equal to 20, then
                       the frames from 1 to (size of dimension 3)-1 will be added.
                       If ALLFRAMES is set, all other parameters are ignored.
           FRAMES    - Array of frames to be added. These values correspond to 
                       indices in the third dimension.  For current data these 
                       are in the range of 1 to 20.
                       If FRAMES may be a single value.
           NFRAMES   - Number of frames to be added.
                       If FRAMES is an array, NFRAMES is ignored.
                       Default value = 1.
     OUTPUTS:
           Add structure arrays 2 and 3 and store the result in structure 8
    
     BACKGROUND:
           CR-39 images are digitized according to the number of tracks with a
           given size in a bin. Low resolution scans are 300 microns/bin.
           High resolution scans are 150 microns/bin.
    
      Frame Number       Track Area (Pixels = 0.299 um^2) / Effective Diam.
             1                 1 to 2 pixels    /  0.617 to 0.872 microns
             2                 3 to 5 pixels    /  1.069 to 1.380 microns
             3                 6 to 10 pixels   /  1.511 to 1.951 microns
             4                11 to 16 pixels   /  2.046 to 2.468 microns
             5                17 to 23 pixels   /  2.544 to 2.959 microns
             6                24 to 32 pixels   /  3.023 to 3.490 microns
             7                33 to 42 pixels   /  3.544 to 3.999 microns
             8                43 to 53 pixels   /  4.046 to 4.492 microns
             9                54 to 65 pixels   /  4.534 to 4.974 microns
            10                66 to 94 pixels   /  5.013 to 5.982 microns
            11                95 to 128 pixels  /  6.014 to 6.981 microns
            12               129 to 168 pixels  /  7.008 to 7.997 microns
            13               169 to 212 pixels  /  8.021 to 8.984 microns
            14               213 to 262 pixels  /  9.005 to 9.987 microns
            15               263 to 378 pixels  / 10.006 to 11.996 microns
            16               379 to 514 pixels  / 12.012 to 13.989 microns
            17               515 to 672 pixels  / 14.002 to 15.995 microns
            18               673 to 851 pixels  / 16.007 to 17.999 microns
            19               852 to 9999 pixels / 18.010 to  112.832 microns
            20               Saturation Frame - Total Number of Pixels with tracks
                                                normalized to the number of pixels
                                                in the bin times 32768.
                        (a value of 16384 means half of the pixels contain tracks)
    
     EXAMPLES:
           Plot the composite of all frames in sturcture 1 except the 
           saturation frame.
             plotstr, addfr(1, /al)
    
           Plot the composite of sturcture 1 frames 3, 4, 5, and 6 
             plotstr, addfr(1, 3, 4)
     or      plotstr, addfr(1, [3, 4, 5, 6])
    
           Store the composite of sturcture 1 frames 3, 4, 5, and 6 in sturcture dog
             dog = addfr(1, 3, 4) 
    
           Store the composite of sturcture 1 frames 3, 4, 5, and 6 in 
           structure array 2
             i2s, addfr(1, 3, 4), 2
    
           Plot frame 5 of structure 2
             plotstr, addfr(2, 5)    ; nframes has a default value of 1
        or   plotstr, addfr(2, 5, 1)
        or   plotstr, 2, 3, 5, /index
    
     MODIFICATION HISTORY:
          Original version, L. P. Mix, November 16, 1998
    

    (See ../pfidl/pfidl_2d/addfr.pro)


    ADDSTR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           ADDSTR
    
     PURPOSE:
           Add a field structure array to a field structure array or to a constant 
           Store the result in the initial field structure array or 
             another structure array
           All attribute or vector quantities are added.
           To combine two structures with partially overlapping domains, 
             see UnionStr.
     CATEGORY:
           Math 
     CALLING SEQUENCE:
           ADDSTR, STR1, STR2,  [, STR3]
           ADDSTR, STR1, 0, VAR, [, STR3]
     INPUTS:
           STR1:    Structure or structure array number of the first structure
                    The output is the same form as the first structure.
                    If STR1 is an IDL structure and the result is to be saved 
                      as an IDL structure in STR3 then the keyword: STRUCTURE 
                      must be set and STR3 must be a variable.
           STR2:    Structure or structure array number of the second structure
      or
           0, VAR    Variable or constant to be added to the first structure
    
     OPTIONAL INPUT:
           STR3:    Structure variable or structure array number for the sum
                    If not specified the sum is stored in STR1 (the first array)
                    The sum is in the same form as the input (STR1).
                    
     KEYWORDS:
           STRUCTURE: Optional keyword which must be present if an idl structure
                    is to be saved in the variable STR3. See example.
           CLABEL:  Optional label for the combined structures.
           MASTER:  Optional grid specification for single block, two dimensional
                    data.  Normally this type of data is put onto a uniform grid
                    with a spacing equal to the minimum spacing anywhere for either
                    grid.  If master = 1, the grid STR1 is used for the result;
                    STR2 is interpolated onto the grid of STR1.
                    If master = 2, then STR1 is interpolated onto the grid for
                    STR2 and the result has the same grid as STR2.
                    If MASTER is positive, the master grid will not be changed.
                    If MASTER is negative (or zero), the master grid will be
                    reduced to the region of overlap between STR1 and STR2.
                    For 3-Dimensional or multi-block data MASTER must be 1 or 2.
                      The data will be put onto the grid of either the first or 
                      second structure array grid.  Missing values are set to zero.
           CUBIC:   If set a cubic interpolation will be used to match single
                    block data on different grids
     OUTPUTS:
           NONE    The sum is stored in a structure array in the common block
     COMMON BLOCKS:
           QSCOM.DAT QSSTRCOM.DAT
     RESTRICTIONS:
         If STR1 or STR2 is a type 8 structure.  
           If str.v1 has the same number of elements as str.v2 then:
             Addstr returns str1.v1+str2.v1 or str1.v1 + VAR
               with the spacial values from STR1.
             If str1.nvect is lt str2.nvect the unmatched vectors from str2 are
               ignored.
    
         For type 1 structures:
         If master is specified, there are no additional restrictions.
           otherwise:
         If not a single block of data and two dimensions then:
           STR1 and STR2 must both be field arrays and have the same number
             of vector components.
           The SIZE of STR1 and STR2 must be the same
           The values of the spatial coordinates must be equal to about 
           3e-5(ie.- max(abs(difference))/max(value) lt 3.1e-5 )
           The check on spatial coordinates is done globally rather than 
             on a block by block basis.
           If a structure has three dimensions, but is degenerate in one of them
             that axis need not be equal.
        If a single block in two dimensions then the data will be interpolated to
           a common spatial scale using a cubic or bilinear interpolation.
     PROCEDURE:
           If STR2 is specified:
               Each attribute, or vector component, of STR1 is added to 
                    each attribute of STR2
           If 0, VAR is specified:
               VAR is added to each attribute of STR1
           In either case, the sum is stored in STR3, if specified, or STR1, 
               if STR3 is not specified.
     EXAMPLES:
           Add structure arrays 2 and 3 and store the result in structure 8
                   ADDSTR, 2, 3, 8
           Add the variable OFFSET to structure  array 2 and store the sum 
           in structure 8
                   ADDSTR, 2, 0, offset, 8
           Add structure arrays 3 and 8 and store the result in structure 10
           with a dataset comment, 'Total Charge - Line + Diode'
                   ADDSTR, 3, 8, 10, c=  'Total Charge - Line + Diode'
           Assume f is an idl structure.
                 ADDSTR, f, 2 ; ADD f to Structure array 2 and return the sum 
                         as an idl structure in variable f.
                 ADDSTR, f, 2, 3 ; Add f to Structure array 2 and return the sum 
                         to structure array 3
                       Note: A warning will be printed. To avoid the warning use:
                               i2s, f, 3 & addstr, 3, 2
                 ADDSTR, f, 2, g, /s ; Add f to Structure array 2 and return the
                               sum as an idl structure in variable g
                      Note: If g is not a variable then the results will be lost.
    
     MODIFICATION HISTORY:
          Original version, L. P. Mix, JULY 15, 1992
          Added MASTER, CUBIC keywords in 1995.
    

    (See ../pfidl/pfidl_2d/addstr.pro)


    ADD_AXIS

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           ADD_AXIS
    
     PURPOSE:
           Add an axis to a model object.
    
     CATEGORY:
           Graphics
    
     CALLING SEQUENCE:
           Model = ADD_AXIS( GEOMETRY [, XRANGE = XRANGE] [, YRANGE = YRANGE] 
                   [, ZRANGE = zrange] [, OFFSET = offset]
                   [, ALENGTH = alength] [, AALENGTH = aalenght]
                   [, ACHARACTER = acharacter] [, /VERBOSE] )
     OUTPUTS:
           Model    - IDLgrModel containing GEOMETRY and the axis
    
     INPUTS:
           GEOMETRY - IDLgrModel containing the solid or IDLgrPolygon
                      (Users may suggest other solid types.)
    
     KEYWORD PARAMETERS:
           XRANGE   - Two element vector defining the extent of the object in 
                      the X direction.  If this is not input, the values will be
                      returned.
           YRANGE   - Two element vector defining the extent of the object in 
                      the Y direction.  If this is not input, the values will be
                      returned.
           ZRANGE   - Two element vector defining the extent of the object in 
                      the Z direction.  If this is not input, the values will be
                      returned.
        Verbose     - If set, data range and axis parameters will be provided.
        OFFSET      - Axis offset from the data as a fraction of the data range.
                      DEFAULT: AOPFFSET = 0.05 
        ALENGTH     - Axis length as a fraction or the data range.
                      If ALENGTH is a 3 element vector, different values will be 
                      used for each vector.
                      DEFAULT: ALENGTH = 0.5
        AALENGTH    - Axis length in data coordinates
                      If AALENGTH is a 3 element vector, these valuse will be used.
                      If AALENGTH is a scalar, greater than zero, this value will
                        be used for all three axes.
                      Otherwise, the actual values will be returned.
                NOTE: AALENGTH is checked before ALENGTH
        ACHARACTER  - Character size as a function of the data range
                      Default = max(.05 * Data Range)
    
     EXAMPLE:
    
           Add a set of axes to the object: oModel
              oModel = add_axis(oModel)
    
     MODIFICATION HISTORY:
          Original version, L. P. Mix, December 2, 2003
    

    (See ../pfidl/pfidl_2d/add_axis.pro)


    ADD_FRAMES

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           ADD_FRAMES
    
     PURPOSE:
           Add frames in a CR-39 digitized image.
           See the function ADDFR.
    

    (See ../pfidl/pfidl_2d/add_frames.pro)


    ALIGNSTR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           ALIGNSTR
    
     PURPOSE:
           Align a streak to an exact horizontal or vertical position by
           rotating the image
           NOTE: The two largest WDF arrays are used as work arrays.
    
     CATEGORY:
           Graphics
    
     CALLING SEQUENCE:
    
           ALIGNSTR, STR1 [, STR2] [, ANGLE = angle] [, SLOPE = slope]
             [, MINBIN = minbin]  [, NP = np] 
             [, SMOOTH = smooth] [, MISSING = missing] 
             [, WIDTH = width]  [, SAVE_ONLY = save_only]
             [, /VERBOSE] [_extra= extrastuff]
    
     where: 
           STR1   - Input Structure
           STR2   - Output Structure (Rotated structure)
                    Default: STR2 = STR1
           ANGLE  - Rotation angle - used in call to rotstr.
           SLOPE  - Slope of the alignment streak
           NP     - Number of points used to obtain alignment.
                    Default = min(total/minbin, 25) > 5 where total is total number
                              of pixels between the limits. 
           MINBIN - Minimum size of lineouts used to determine feature.
                    Default = (11 < (total/5))> 1  where total is total number
                              of pixels between the limits.
                    Actual number will always be odd
           SMOOTH - Size of Boxcar filter
                    Default = 9
           WIDTH  - Half Width of the feature used for alignment 
                    Center +/- width is used to align the image
                    Default = 2% = .02 
           MISSING- Value for data missing in the rotation
                    See POLY_2D for description 
           VERBOSE- See the calculation of FWHM and other diagnostics
           SAVE_ONLY - Do not rotate image.  Save the streak to the wdf defined
                    by SAVE_ONLY.  If SAVE_ONLY is set but does not have a valid 
                    WDF array, then use get_maxwdf()-1
           _EXTRA - Keyword parameters for plotfld (Xrange, Yrange, etc)
    
    	
     OUTPUTS:
           STR1 is rotated so that the feature is horizontal or vertical
             The rotated structure is stored in STR2.  If STR1 is a structure
             array number then STR2 will be also.  If STR1 is a structure, then 
             so also will be STR2.
    
           RotStr is used to rotate the structure
    
     PROCEDURE:
           1. User is asked to indicate top and bottom or left and right extreme
              of the alignment feature.  All calculations are performed using 
              bins.
           2. NP Lineouts are taken
           3. Lineouts are smoothed.
           4. Lineouts are limited to indicated point +/- Width.
           5. FWHM is calculated using a baseline of the average of first and last
              Width/2
           6. The average of the leading and falling half width points are used
              as the peak center.
           7. These peak values are used with a least squares fit to determine 
              the amount of rotation required.
           8. The image is rotated with ROTSTR
           9. The image is stored
           
              
     EXAMPLE:
           Rotate structure 1 and save aligned structure in 4
              alignstr, 1, 4
    
           Calculate the points on a line feature in structure 1 and store in wdf 5.
              alignstr, 1, save=5
    
     MODIFICATION HISTORY:
     	Written by:	L. Paul Mix, June 26, 2000
                           Added save_only keyword, February 3, 2004.
    

    (See ../pfidl/pfidl_2d/alignstr.pro)


    ARR2STR

    [Previous Routine] [Next Routine] [List of Routines]
       Convert a two, three, or four dimensional array to a field type structure array
         with one or more vector components
       Five and Six dimensional data may also be written but this data is not generally
         supported.
       Single block data only, but JOINSTR may be used to combine into a single str.
       Format:
         ARR2STR, STR, IMAGE, image2, image3, femesh = femesh, plotit = plotit,  
           x, y, z, t, u, v, dx = dx, dy = dy, dz = dz, dt = dt, du = du, dv = dv, 
           /structure_only, tlabel = tlabel, clabel = clabel, grid = grid, file = file,
           xlabel = xlabel,  ylabel=ylabel, zlabel = zlabel, x4label = x4label, 
           x5label = x5label,  x6label = x6label,
           v1label = v1label, v2label = v2label, v3label = v3label, 
           connectivity = connectivity, spare = spare
    
         where: (REQUIRED)
              STR    - Structure array number where data is stored
                       If structure_only is set, STR is a structure generated
                       from the input data
              IMAGE  - 2D, 3D, or 4D array (5D and 6D arrays may also be used)
                       Note:  Use JOINSTR for multiple block data.
                       Note:  5 and 6 dimensional arrays are for special applications
     (OPTIONAL)
              image2, image3 - Additional images for a Vector type field structure
                Note: Image, image2 and image3 must all be the same size
              x      - Vector of x values, must be as big as first dimension
              y      - Vector of y values, must be as big as second dimension
              z      - Vector of z values, must be as big as third dimension
                       If nx*ny*nz eq nI and (size(image))[0] eq 2, a three dimensional 
                       structure will be generated with a degenerate dimension, 
                       where ni = n_elements(image), nx = n_elements(x),
                         ny = n_elements(y), and nz = n_elements(z).
              t      - Vector of t values, must be as big as fourth dimension
              u      - Vector of u values, must be as big as fifth dimension
              v      - Vector of v values, must be as big as sixth dimension
          (Note:  The following values will be calculated if not present.)
              dx     - Spacing of X values
              dy     - Spacing of Y values
              dz     - Spacing of Z values
              dt     - Spacing of T values
              du     - Spacing of U values
              dv     - Spacing of V values
     Keywords:
              GRID   - If set, data is a grid dataset.
                       Number of dimensions must be 2 or 3. 
                       Current implementation does not allow FE meshes.
                       IMAGE is the X array
                       IMAGE2 is the Y array
                       IMAGE3 is the Z array if 3 dimensional data.
                       for example: arr2str, 4, x, y, z , /grid
                         will return a type 3 dataset with x, y, and z as the 
                         grid values.
              FEMesh - If set, Data is from a finite element type, random mesh.
                       Default: FEMesh = 0; rectilinear mesh.
                       If set, X, Y are required and only 1 image is allowed.
                       Image, x, and y are linear arrays.
                  Format: arr2str, /fem, str, image, x, y, etc.
                  NOTE: See CONNECTIVITY
              CONNECTIVITY: Connectivity of the finite element mesh.  This is 
                            ignored for rectilinear data.
                            If Connectivity is not specified, TRIANGULATE will be used.
              PLOTIT - Ignored unless FEMesh is set. Plots the triangles.
              clabel - Comment Label
              tlabel - Type Label
              xlabel - X-Label
              ylabel - Y-Label
              zlabel - Z-Label
              x4label- T-Label
              x5label- U-Label
              x6label- V-Label
              v1label- Vector 1 label
              v2label- Vector 2 label
              v3label- Vector 3 label
              spare  - spare keyword
                       Default = [0,0,0,0,0]
              file   - Associated file 
              Structure_Only - If set STR is returned as a structure.
              
          Example:
              Make a structure array from array, picture, and put it into 4 
                arr2str, 4, picture, clab = 'filtered image'
    
              Make a structure array from arrays, vx, vy and vz with spatial
                coordinates, xval, yval, zval and store into structure 18
                ARR2STR, 18, vx, vy, vz, xval, yval, zval, $
                   clab = 'Particle velocity'
    
    

    (See ../pfidl/pfidl_2d/arr2str.pro)


    BORDER

    [Previous Routine] [Next Routine] [List of Routines]
        This routine calculates the values along the minimum or maximum dimension
          of a structure array.  The structure array must be two dimensional or be
          three dimensional with a degenerate dimension and a single attribute.
    
        Format:  BORDER, STR, SIDE, WDA, TOP = top, PLOT = plot
          where:
             STR    - Field structure or a QS structure array number
             SIDE   - Indicates the coordinate for which the minimum or maximum 
                      is desired
             WDA    - Waveform array to store the values
             TOP    - If present and not zero, the values of the structure at the 
                      maximum value of SIDE will be returned.
            PLOT    - If present and not zero, a plot of the values will be made
        Example:
          Store in WDF array 34, the value at minimum r for structure 2
          Average the second spatial dimension between -1 and 10.
          Use the second component of the field.
             tempstr = slice(2, 2, 2, [-1, 10])   )
             border, tempstr, 1, 34
    

    (See ../pfidl/pfidl_2d/border.pro)


    CHASTR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           CHASTR
    
     PURPOSE:
           Change the prameters of a structure array 
           The following types of structures arrays are supported 
             valid_typ = [1, 2, 3, 4, 7, 8, 9, 10]
           Changes which do not apply to a particular structure type are ignored 
           
     CATEGORY: 
           Utility 
     CALLING SEQUENCE: 
           CHASTR, STR 
     INPUTS: 
           STR:      Structure array number or an array of structure array 
                     numbers to be changed.  If only one structure is specified,
                     then it may be an IDL structure.
     KEYWORD PARAMETERS:
           CLABEL    Replace the dataset comment for the structures specified by
                     STR with the string or string variable specified
           XLABEL    Replace the first spatial dimension label for the specified
                     structures with the string or string variable specified
           YLABEL    Replace the second spatial dimension label for the specified
                     structures with the string or string variable specified
           ZLABEL    Replace the third spatial dimension label for the specified
                     structures with the string or string variable specified
           TLABEL    Replace the fourth spatial dimension label for the specified
                     structures with the string or string variable specified
           ALABEL    Replace the all spatial dimension labels for the specified
                     structures with the string or string variable specified
           V1LABEL   Replace the first attribute label or the first vector label
                     for the specified structures with the string or string 
                     variable specified
           V2LABEL   Replace the second attribute label or the second vector label
                     for the specified structures with the string or string 
                     variable specified
           V3LABEL   Replace the third attribute label or the third vector label
                     for the specified structures with the string or string 
                     variable specified
           V4LABEL   Replace the fourth attribute label or the fourth vector label
                     for the specified structures with the string or string 
                     variable specified
           V5LABEL   Replace the fifth attribute label or the fifth vector label
                     for the specified structures with the string or string 
                     variable specified
           V6LABEL   Replace the sixth attribute label or the sixth vector label
                     for the specified structures with the string or string 
                     variable specified
           VALABEL   Replace the all attribute labels or all vector labels
                     for the specified structures with the string or string 
                     variable specified
           MXDIM     Multiply the first spatial dimension by this value
           MYDIM     Multiply the second spatial dimension by this value
           MZDIM     Multiply the third spatial dimension by this value
           MTDIM     Multiply the fourth spatial dimension by this value
           MADIM     Multiply all spatial dimensions by this value
                     MADIM depends on the first spare word in the first structure
                     If SPARE[0] eq 2 then ONLY MXDIM = MZDIM = MADIM
                     If SPARE[0] eq 3 then ONLY MXDIM = MADIM
                     Else:  MXDIM = MYDIM = MZDIM = MTDIM = MADIM
           AXDIM     Add this offset to the first spatial dimension
           AYDIM     Add this offset to the second spatial dimension
           AZDIM     Add this offset to the third spatial dimension
           ATDIM     Add this offset to the fourth spatial dimension
           AADIM     Add this offset to all the spatial dimensions
           NOTE:  Multiplication and division are performed according to:
                  Xnew = Xold * MXDIM + AXDIM
           S1V       Multiply or scale the first vector or attribute component
           S2V       Multiply or scale the second vector or attribute component
           S3V       Multiply or scale the third vector or attribute component
           S4V       Multiply or scale the fourth vector or attribute component
           S5V       Multiply or scale the fifth vector or attribute component
           S6V       Multiply or scale the sixth vector or attribute component
           SCALE     Multiply all the vector amplitudes by a scale factor.
                     This is identical to:  mulstr, str, 0, scale
           SPACE     If SPACE is present and not zero, then S1V, S2V, ..., SCALE
                     must have values of 1, 2, or 3. The scaling will be of the 
                     form: V1 = X1(i)*v1(i, *, *) for s1v = 1
                       or  V1 = X2(i)*v1(*, i, *) for s1v = 2 
                       or  V1 = X3(i)*v1(*, *, i) for s1v = 3 
                       for example to multiply vector 2 by r (r*btheta)
                         USE: chastr, Bfield, s2v =1, /space
                     or if SPACE is a string function of X then:
                       if s1v = 1 then 
                            x = X1
                           V1 = string *v1(i, *,*)
                       if s1v = 2 then 
                            x = X2 ... etc 
                     for example to multiply vector 1 by sin(theta)
                      (string may be any executable idl or user function)
                        chastr, str, s1v =2, space = 'sin(x)'
                     If V1LABEL is not specified it will be modified to reflect 
                       this scaling, ie, v1label = labx+' * '+labv 
                       where labx is the spatial label and labv is the vecor label
                       (See example)
           FILE      Replace the file name with the string specified
     OUTPUTS:
           NONE    The specified structures are modified and stored in their
                   original locations
     COMMON BLOCKS:
           QSCOM, QSSTRCOM 
     RESTRICTIONS:
           STR array must be defined and have valid data
     EXAMPLES:
           Change the dataset comment to 'Stream Functions at 65 ns' on structure
              array 2
                CHASTR, 2, c = 'Stream Functions at 65 ns'
           Change the x and y spatial coordinates of an image by 1/maginfication
                CHASTR,IMAGE,mx=1/.56, my = 1/.56,xl='Target(cm)',y='Target(cm)'
           Change the spatial coordinates of arrays 2 through 9 to cm from meters
                CHASTR,indgen(8)+2,ma=1e2,x= 'X (cm)',y='Y (cm)',z='Z (cm)'
             Note in cylindrical coordinates we would use:
                CHASTR,indgen(8)+2,mx=1e2, mz = 1e2, x ='Radius(cm)',z='Z(cm)'
           Change the units of electric field to MV/cm from V/m on structure, F
                CHASTR, F, sa= 1./1e8,v1='Ex(MV/cm)',v2='Ey (MV/cm)',v3='Ez(MV/cm)'
           Change the radial component of the field in structure, F, from Er to r*Er
                CHASTR, F,s1v =1, /space
           
     MODIFICATION HISTORY:
          Original version, L. P. Mix, November 16, 1993
    

    (See ../pfidl/pfidl_2d/chastr.pro)


    COND_RANGE

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           COND_RANGE
    
     PURPOSE:
           Determine conductor extent at a plane in space
     CATEGORY:
           Utility
     CALLING SEQUENCE:
           COND_RANGE, A , X , Y , Z [, IER]  [, XRANGE = xrange] 
               [, YRANGE = yrange] [, ZRANGE = zrange] 
     INPUTS:
           A     IDL conductor  structure or structure array number (type = 4)
     Note: Only 2 of the following parameters will be passed with valid data.
           The remaining parameter will be returned with the minimum and maximum
           values of the conductor.  If no conductors are found 
    
           X     First coordinate value or range of values where the conductor 
                   extent is desired
           Y     Second coordinate value or range of values where the conductor 
                   extent is desired
           Z     Third coordinate value or range of values where the conductor 
                   extent is desired
         Note: An error tolerance of 2^(-16) is used  in determining whether
                  a plane crosses a conductor, that is,
               maxp = max(a.plane(1, *, *))
               minp = min(a.plane(0, *, *))
               err = 1.52588e-5*( max([maxp-minp, abs(maxp), abs(minp)]))
           IER   Error parameter
                 0 if maximum gt minimum+err
                 1 if maximum eq minimum
                -1 if no conductors are found
    
     KEYWORD PARAMETERS:
           X,Y,ZRANGE - Axis range(standard IDL meaning)
                    Note: If multiple keywords are set, only the first 
                          detected will be used in order: Xrange, Yrange, Zrange
    
     EXAMPLE:
           Determine the conductor radial extent for conductor structure 4 at 
             theta = 0, and z = 4
           COND_RANGE, 4, r, 0, 4, /x
           Note: r(0) will be the minimum value of the conductor
                 and r(1) will be the maximum value of the conductor.
    
    
     MODIFICATION HISTORY:
          Original version, L. P. Mix, August 2, 1993
    

    (See ../pfidl/pfidl_2d/cond_range.pro)


    CYL2CART

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           CYL2CART
    
     PURPOSE:
           Convect a cylindrical geometry to a rectilinear geometry.
           The result will be a type 8, finite element mesh in x and y.
                            
           Three vector data will be convected to rectilinear data.
             The three vectors are assumed to be Vr, Vtheta, and Vz.
             They are transformed to Vx, Vy, and Vz.
           Scalar data (single vector) data is not modified.
    
     CALLING SEQUENCE:
           STR2= CYL2CART( STR1, [, ZVALUE] [, INDEX = index] [, /PSEUDO]
                 [, CLABEL = clabel] [, XLABEL = xlabel] [, YLABEL = ylabel]
                 [, SAVE = save] [, HELPME = helpme] )
                      
     INPUTS:
           STR2    Field structure with Cartesian data on a finite element mesh.
                   If SAVE is set, STR2 = 0, that is the following is executed:
                     i2s, str2, save, /no_copy & return, 0
                   If an error occurs, STR2 = -1.
             Note: To check for an error in CYL2CART, use the following.
                     str2 = cyl2cart(str1, zvalue)
                     if (size(str2, /type) lt 8) then $
                       if str2 eq -1 then print, 'Error occured in CYL2CART'
             Note: If a structure is returned or if 0 is returned, then no error.
           STR1    Structure array number or field structure with Cylindrical data
                   on a rectilinear (r, thets, z) mesh
           ZVALUE  Slice value in the Z direction.
                   If STR1 is a two dimensional field then this value is ignored
                   If STR1 is a three dimensional field then this value
                   indicates the coordinate value for the fixed dimension in
                   the two dimensional plots. Linear interpolation is used
                   according to the value of ZVALUE. If ZVALUE has two elements
                   the average value over the interval is used.
                   Note: If Zvalue is not valid, then the closest Z value is used.
             Note: If INDEX keyword is set, the units are taken as array indices
                   which range from 1 to the maximum value. 
                   Caution: Multiple block data has may produce unexpected results.
             Note: If the two elements of ZVALUE span a block boundary, then only
                   the values in the block containing the midpoint will be used.
                   If the midpoint falls on a block boundary, then the result is
                   probably not what you want!!
           INDEX   If set, units of ZVALUE are Z indices in each block which can
                   range from 1 to n_elements(z)
                   Default: INDEX = 0
           XLABEL  X Label Value to be used X1LAB
                   Default: X1LAB = 'X'
           YLABEL  Y Label Value to be used X2LAB
                   Default: X2LAB = 'Y'
           CLABEL  Comment value to be used CLABEL
                   Default: CLABEL = 'Cartesian '+str1.clab
           PSEUDO  If set(/p), a pseudo cylindrical plot is made.
                   (This is useful for plotting timing data from an accelerator
                     where the lines are arranged in a circle.)
                   This is limited to single block, scalar, 2D data.
                   X is assumed to run from (MIN(X) < 1) to N. 
                   Y is time or some similar quantity
                   The first value will be put on the positive Y axis and the
                   remaining points will be uniformly spaced around the circle.
                   If PSEUDO <= 2 then N = MAX(str1.x1) else N = PSEUDO
                   If PSEUDO has 2 elements then they will be taken as the minimum 
                     and maximum values.
           OFFSET  If PSEUDO is set, the radius (Y value) will be reduced by OFFSET.
                   This value will be returned in OFFSET. 
           SAVE    If set, save STR2 in a structure array.  Valid values are
                   [1, get_maxstr()]  If SAVE is set, 
                     then save = save if positive and <= get_maxstr()
                               = first unused structure array number
                               = get_maxstr() if all arrays are full
           HELPME  If set, a help message will be printed
    
     EXAMPLE:
           Convect structure f to fxy at the value of Z = 4.5
             fxy = cyl2cart(f,4.5)
    
           Convect structure 5 to a cartesian structure and store the
           result in structure 45.  Slice at a value of 3
             junk = cyl2cart(5, 3, s =45)
    
           Convect structure 5 to a cartesian structure and store the
           result in structure 45, 46 and 47  for Z-planes 1, 2 and 3.
             for i = 1, 3 do junk = cyl2cart(5, i,/index save=44+i)
     Note: To get vectors in a plane. Vx component in this example and save in 21
           To see the plot
             plotstr, str2, 1, work = 21, cn=2 
           or to just get the data
             plotstr, str2, , result = 21, /nf, /quiet
                          (results in 128 by 128 array)
                          (change nfarray to get a different number)
    
     MODIFICATION HISTORY:
          Original version, L. P. Mix, April 7, 1999
    

    (See ../pfidl/pfidl_2d/cyl2cart.pro)


    DELSTR

    [Previous Routine] [Next Routine] [List of Routines]
      format: delstr, STR
      This routines clears structure arrays
      If STR is zero or undefined; all arrays are cleared.
      Otherwise, all valid structure arrays specified by STR are cleared.
      example:
      clear all structure arrays
          delstr
     or   delstr, 0
    
      clear structure array number 15 and 18
          delstr, [15, 18]
    
    

    (See ../pfidl/pfidl_2d/delstr.pro)


    DIRS

    [Previous Routine] [Next Routine] [List of Routines]
    
     NAME:
          DIRS
     PURPOSE:
          Show the structures in the qs common area which contain data
     CALLING SEQUENCE:
          DIRS  [, SMIN] [, SMAX] [, TRUNCATE = truncate] [, Xsize = xsize]
                [, PAGE = page]
     INPUTS:
          SMIN   - First sturcture array number to be listed or an array of 
                   structure array numbers or a QS structure
             or
                 If a single parameter, SMIN can be a search string.
                 Those arrays containing the string in the dataset comment will
                   be listed. The full set of wild card options is available.
                   See GET_MATCH
          SMAX   - Last structure array number
          TRUNCATE - If set, the dataset comments will be truncated at ' - '
                   This is a toggle; If not specified the last value will
                   be used.  Default value =0 -- no truncate
          PAGE   - Number of lines on the directory
          XSIZE  - Width of the window in pixels (generally not set)
          RESET  - If set, a new window will be opened.
     Outputs:
          Structure parameters in a widget 
     Example:
          See the contents of all structure arrays
             DIRS
          See the structures with E-field in the comment
             DIRS, 'E-field'
          See the full contents of structure arrays 1 through 13
             DIRS, 1, 13
     (or)    DIRS, 1+indgen(13)
    

    (See ../pfidl/pfidl_2d/dirs.pro)


    DIVSTR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           DIVSTR
    
     PURPOSE:
           Divide a field structure array to another field structure array 
             or by a constant 
           Store the result in the initial field structure array or 
             another structure array
           All attribute or vector quantities are divided.
     CATEGORY:
           Math 
     CALLING SEQUENCE:
           DIVSTR, STR1, STR2,  [, STR3]
           DIVSTR, STR1, 0, VAR, [, STR3]
     INPUTS:
           STR1:    Structure or structure array number of the first structure
                    The output is the same form as the first structure.
                    If STR1 is an IDL structure and the result is to be saved
                      as an IDL structure in STR3 then the keyword: STRUCTURE
                      must be set and STR3 must be a variable.
           STR2:    Structure or structure array number of the second structure
      or
           0, VAR    Variable or constant to divide into the first structure
     OPTIONAL INPUT:
           STR3:    Structure or array number for the quotient, if not specified 
                    the quotient is stored in STR1 (the first array)
                    The quotient is in the same form as the input (STR1).
     KEYWORDS:
           STRUCTURE: Optional keyword which must be present if an idl structure
                    is to be saved in the variable STR3. See example.
           DEFAULT: Value used for Division by zero.
                    Zero is defined as AZERO + MAX(ABS(STR))*RZERO
                    DEFAULT: DEFAULT = 0.0
           AZERO:   Absolute Value of zero for the above default value.
                    Default = 0.0
           RZERO:   Relative value of zero compared to the maximum value.
                    Default = 2.3841858e-07 = (2^(-22))
           CLABEL:  Optional label for the combined structures.
           MASTER:  Optional grid specification for single block, two dimensional
                    data.  Normally this type of data is put onto a uniform grid
                    with a spacing equal to the minimum spacing anywhere for either
                    grid.  If master = 1, the grid STR1 is used for the result;
                    STR2 is interpolated onto the grid of STR1.
                    If master = 2, then STR1 is interpolated onto the grid for
                    STR2 and the result has the same grid as STR2.
                    If MASTER is positive, the master grid will not be changed.
                    If MASTER is negative (or zero), the master grid will be
                    reduced to the region of overlap between STR1 and STR2.
                    For 3-Dimensional or multi-block data MASTER must be 1 or 2.
                      The data will be put onto the grid of either the first or 
                      second structure array grid.  Missing values are set to one
           CUBIC:   If set a cubic interpolation will be used to match single
                    block data on different grids
     OUTPUTS:
           NONE    The quotient is stored in a structure array in the common block
     COMMON BLOCKS:
           QSCOM.DAT QSSTRCOM.DAT
     RESTRICTIONS:
           STR1 array must be defined and have valid data
           STR2 or 0 and a Variable must be defined
         If master is specified, there are no additional restrictions.
           otherwise:
         If not a single block of data and two dimensions then:
           STR1 and STR2 must both be field arrays and have the same number
             of vector components.
           The SIZE of STR1 and STR2 must be the same
           The values of the spatial coordinates must be equal to about 
           3e-5(ie.- max(abs(difference))/max(value) lt 3.1e-5 )
           The check on spatial coordinates is done globally rather than 
             on a block by block basis.
           If a structure has three dimensions, but is degenerate in one of them
             that axis need not be equal.
         If a single block in two dimensions then the data will be interpolated to
           a common spatial scale using a cubic or bilinear interpolation.
     PROCEDURE:
           If STR1 or STR2 is a type 8 structure.
           If str.v1 has the same number of elements as str.v2 then:
             MULSTR returns str1.v1*str2.v1 or str1.v1*VAR
               with the spacial values from STR1.
             If str1.nvect is lt str2.nvect the unmatched vectors from str2 are
               ignored.
    
         For type 1 structures:
           If STR2 is specified:
             Each vector component, of STR1 is divided by
                    each vector component of STR2
           If 0, VAR is specified:
                Each attribute of STR1 is divided by VAR
           In either case, the quotient is stored in STR3, if specified, or STR1, 
              if STR3 is not specified.
           The quotient is set to DEFAULT for all values of STR2 less than 
             2.3841858e-07 of the maximum value of each attribute or the value
             determined by AZERO and RZERO.
     EXAMPLES:
           Divide structure array 2 by 3 and store the result in structure 8
                   DIVSTR, 2, 3, 8
           Divide the variable OFFSET into structure array 2 and store the quotient
           in structure 8
                   DIVSTR, 2, 0, offset, 8
           Divide structure array 3 by 8 and store the result in structure 10
           with a dataset comment, 'Total Impedance - Voltage/current'
                   DIVSTR, 3, 8, 10, c=  'Total Impedance - Voltage/current'
           Assume f is an idl structure.
                 DIVSTR, f, 2 ; Divide f by Structure array 2 and return the 
                         quotient as an idl structure in variable f.
                 DIVSTR, f, 2, 3 ; Add f to Structure array 2 and return the 
                         quotient to structure array 3
                       Note: A warning will be printed. To avoid the warning use:
                               i2s, f, 3 & addstr, 3, 2
                 ADDSTR, f, 2, g, /s ; Add f to Structure array 2 and return the
                          quotient as an idl structure in variable g
                      Note: If g is not a variable then the results will be lost.
     MODIFICATION HISTORY:
          Original version, L. P. Mix, JULY 15, 1992
    

    (See ../pfidl/pfidl_2d/divstr.pro)


    EDITSTR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           EDITSTR 
    
     PURPOSE:
           Edit a 2-D structure - Specified area is set to the average border value
             or a user specified value.  The user may also set the value outside a 
             specified region.
           Procedure will generate windowed regions and display them. 
             User may set windowed region to background or a user value.
             Region may be rectangular, circular or elliptical.
           A preview gives the window before storage. A preview will be generated
             whenever the mouse moves in the window and one point has been 
             selected.  The preview frame may be resized.
           Note: Some time is required to calculate a preview frame. All events
                 generated while the preview frame is generated are deleted; be
                 sure the mouse clicks are acknowledged before proceeding.
           Mouse buttons are mapped to widget buttons, cursor must be in the 
             DRAW area of the main widget for the following mouse commands.
              Left Button   = Set Value
                 Note: A carriage return in the data field will also set the value.
              Middle Button = Accept/Save
                 (current designated windowed image will be saved)
              Right Button  = Reset All Points
                 (All points will be undesignated)
              Note: If a the last point required to define a curve is selected 
                    more than once, the previous "last point" is replaced.
           Set Point Buttons: These perform the same function as a  in either
                              the X or Y windows above the buttons.
    
     CALLING SEQUENCE:
    	EDITSTR, STRin [, STRout] [, X, Y] [, XVALUE = X, YVALUE = Y]
    
       where:
           STRin - Structure array number of a two dimensional structure or 
                   a slice from three dimensional structure.
                   This structure will be overwritten if STRout is not specified.
                   The structure should be single block for maximum resolution.
              NOTE: MaxStructure and MaxStructure-1 are used as work arrays.
             
           STRout- Structure array number of a two dimensional structure or 
                     an output variable.  Default: STRout = STRin
                   NOTE:  If STRout has more than 1 element, it is assumed to be 
                          the parameter X
           X, Y - 2N X-values and 2N Y-values to specfy the region for editing
                  N is the number of edit regions
                  If they are present, no gui will be generated and the N regions 
                  will be edited.
                  Note: XValue and YValue are used if they are provided with two or
                        more values.
    
     KEYWORD PARAMETERS:
           XVALUE, YVALUE:  See X, Y parameters
                     NOTE:  XVALUE and YVALUE are used if provided.
           CIRCLE:   If set, the edit shape will be a circle 
               Note: If CIRCLE is set, ELLIPSE is ignored.
           ELLIPSE:  If set, the edit shape will be an ellipse  
               Note: If CIRCLE is set, ELLIPSE is ignored.
           INVERTIT: If set set the values outside the shape.
           EDIT_VALUE: Returns the last value used for the EDIT VALUE
                       This may be the border value or a user value depending on settings
           AVERAGE:  Returns the average for the last rectangular area selected
                     NOTE: This is for the rectangular region defined by the two points
                           and does not depend on the shape of the edit region.
                     NOTE: This value will be the average inside the rectangular region.
                           If the image is edited in interactive mode, the average inside
                           the rectangular region will reflect the edited values and not
                           the original image.  In batch mode, the average is the average
                           before editing.
           NOEDIT:   If set, the image will not be changed in batch mode but the AVERAGE 
                     and EDIT_VALUE are returned.  This only applies to the last set of
                     points if more than two points are provided.         
           USER_VALUE: If N_ELEMENTS(USERVALUE) gt 0, then the selected region will 
                       changed to USER_VALUE[0] rather than the border average.
                       This value may be edited.
                       The user value or border average will be displayed dynamically
                       after two points are selected.
           KEEP_ASPECT: Keep same aspect ratio in the preview window as in the
                        primary window.  Default: KEEP_ASPECT = 0
                        If KEEP_ASPECT is negative, the color map will also be kept.
                 NOTE:  Set the ASPECT keyword in EDITSTR to have the proper 
                        aspect ratio in the primary window.  (See _EXTRA below.)
           _EXTRA:     Any valid keyword for plotfld. The array for the windowing
                       is generated with the following command and this plot is 
                       used for the image:
                          PLOTFLD, str, cn=2, _extra = extrastuff
     PROCEDURE:
           A section of the image is selected.  The user may set the central
           portion of the selected image to the average around the the exterior or 
           to a user specified value.
           Note:  The values specified in the windows are moved to the nearest node.
                  All nodes in the specified region are changed.
       NOTE: MaxStructure and MaxStructure-1 are used as work arrays.
        Buttons:
           Border Value - replace region values with the image border average 
                          The border average is the pixel adjoining the selected area.
                          No values are used on sides that include the image border.
                          For curved areas, only values above and below the area
                            are used.
           User Value   - replace region values with the user specified value
           Edit Value   - Actual value to be used.  May be edited in the user mode
                          In Border mode, the value may be seen by switching
                          to user mode; after reading the value the mode should be
                          returned to "Border" mode if Border mode is desired.
           Rectangle    - Define the edit region using the two points
           Circle       - Define the edit region with a circle in the middle of the 
                          two points.  The radius is sqrt(dx*dy)/2 where dx and dy
                          are the horizontal and verticle spacings of the two points.
           NOTE:  The average, minimum, and maximum are calculated for the rectangular 
                  region.
           Ellipse      - Define the region with an ellipse tangent to the rectangle
                          defined by the two points.
           NOTE:  The average, minimum, and maximum are calculated for the rectangular 
                  region.
           Invert       - Change the values outside the selected region.
           Edit Region  - Change the value in the region.
           Move Area    - If checked, the center of the region will be moved.
                          If not checked, POINT_2 will be moved
           Accept/Save  - Modify the image with the new values.
           Reset All Points - Unset both the first and second points
                          All modifications to the array since the last save are erased
           UNDO         - Eliminate the last "Accept/Save Image" 
           Done/Exit    - Exit and save the current image.
    
     EXAMPLE:
    	Eliminate a number of marks on images from structure array 3 and
             store the result in structure array 11.
               EDITSTR, 3, 11
    
           Edit structure 4 and save the result in structure 12.  Use a circular
             edit region and replace all places with a value of .01
               EDITSTR, 4, 12, user=0.01, /circle
    
           Determine the average of structure 2 in an area without data and use 
             the average value of the rectangular region defined byt the two points
             selected to subtract a background.
               EDITSTR, 2, average = aver
               SUBSTR, 2, 0, aver
    
     MODIFICATION HISTORY:
     	Written by:	L. P. Mix, January 7, 2003
           Modified: LPM, February 1, 2004
                     Change edit region shapes, add user value and allow spot motion.
           Modified: LPM, June 1, 2005
                     Added batch option and AVERAGE and EDIT_Value keywords
    

    (See ../pfidl/pfidl_2d/editstr.pro)


    FILM_EXP

    [Previous Routine] [Next Routine] [List of Routines]
     Name:
           FILM_EXP
    
     PURPOSE:
           Convert film density to relative exposure using a particular
           film response curve.
    
     Format:
           FILM_EXP, STR1 [, STR2], RESPONSE = response
      Where:
           STR1     - Structure array number of film image in density
           STR2     - Structure array number of film image in relative exposure 
                      If str2 is undefined then str2 = str1
           RESPONSE - Ignored since we only have one response curve.
                      (D7)
     Example:
           Convert structure 1 to relative exposure and store in structure 2
             FILM_EXP, 1, 2
    
    ; MODIFICATION HISTORY:
          Original version, L. P. Mix, December 9, 1997
    

    (See ../pfidl/pfidl_2d/film_exp.pro)


    FLIPSTR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
    	FlipSTR
    
     PURPOSE:
    	Flip or rotate an image
           NOTE:  AXIS values are unchanged except in the case of a rotation, 
                  The X and Y axis will be switched if necessary.
                  If the axis is not uniform, the values will be flipped.
                  
    
     CALLING SEQUENCE:
    	FLIPSTR, STR, [, SAVE]  [, /XFlip ] [, /YFlip ]
                   [, ROTATE = Rotate_Code]
    
     INPUTS:
    	STR:	The image array to be flipped.  This is a field type structure
                   or structure array number. It must have two dimensions with 
                   uniform point spacing.
    	SAVE:	Structure array number for the flipped image.
                   If str is a structure array number, then the flipped
                     image will be saved as a structure array number.
                   If str is a structure , then the flipped
                     image will be saved as a structure.
                   Default: If SAVE is missing, flipped image will be returned
                     in STR.
           XFLIP:  Reverse the X-Direction (reverse(str, 1))
           YFLIP:  Reverse the Y-Direction (reverse(str, 2))
           ROTATE: Rotation code defined in IDL manual
                   1, 2, 3  : Counterclockwise Rotation by 90, 180 and 270 degrees 
                   4        : Transpose Array
                   5, 6, 7  : Transpose and Counterclockwise Rotation 
                              by 90, 180 and 270 degrees
                   Note: Rotate = 5 is the same as XFlip
                   Note: Rotate = 7 is the same as YFlip
                   If ROTATE equal 5 or 7, then XFLIP or YFLIP will be used.
    
     OUTPUTS:
    	FLIPSTR returns a flipped version of the input image.
    
     PROCEDURE:
    	REVERSE and ROTATE are used to rotate the image.
           If rotate equals 1, 3, 4, or 6 then the X and Y AXES are reversed.
           Only one operation is performed on a call.  XFLIP, YFLIP and ROTATE 
           are checked in order and the first valid command terminates the program.
           If the coordinates are uniform, the values will not be changed.
           If the coordinates are not uniform, the coordinates will be changed
           according to the equations for x (Y is identical):
             nx = N_elements(x)
             x = reverse(x[0]+x[nx-1]-x)
    
     EXAMPLE:
    	Invert structure 1 in the y direction.
    		FLIPSTR,1, /y
    
           Invert structure 2 in the X direction and store the result in 2
    		FLIPSTR,1, /x, 2
      
     MODIFICATION HISTORY:
           Original version: August 16, 2000, lpm
    
    

    (See ../pfidl/pfidl_2d/flipstr.pro)


    GETDIM

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           GETDIM
    
     PURPOSE:
    	Convert a linear index as returned from the WHERE command to a set
           of indices for the location
           NOTE:  IDL will always allow a linear (one dimensional) index 
                  to access elements of a multi-dimensional array.
    
     CALLING SEQUENCE:
     
    	IND = GETDIM(ARRAY, INDEX)
    
     PARAMETERS:
           IND:    Array of indices
                   The first index of IND equals the number of dimensions
                   of the input ARRAY.
                   The second index of IND equals the number of elements in
                   INDEX.
    	ARRAY:  Array for which the indices are desired.
                   or
                   Linear array of dimensions for each coordinate.
                   DIMENSIONS must be set for this option.
           INDEX:  One dimensional index to be converted to components.
                   INDEX may be an array of one dimensional indices.
           DIMENSIONS: If set, ARRAY is a linear array of dimensions.
    
     OUTPUTS:
           The only normal output is the array IND with the multi-dimensional 
           indices.
    
     PROCEDURE:
           The procedure is a loop.
           IND is the array of indices.
           INDEX is the one dimensional index
           NDIM is the number of dimensions and SS[i] are the number of
           elements for the Ith dimension.
           D=1L
           for i = 0, ndim -2 do begin
             IND[i] = INDEX/D mod ss[i+1]
             D = D * SS[i+1]
           endfor
           IND[ndim-1] = INDEX/d
    
     EXAMPLE:
           Find the coordinates of the maximum value of an array, PICT, and
           print the coordinates.  X and Y are the coordinates for PICT.
             maximum = max(PICT, J)
             IND = getdim(PICT, J)
             print, 'Maximum of the picture is', maximum, '
             print, 'Coordinates are: ', X[ind[0]], Y[ind[1]]
    
           Using the values in the first example: PICT, X, Y
           Print the X and Y locations where PICT is greater than 5.
             ok = where (PICT gt 5, nok)
             if nok gt 0 then begin
               print, 'PICT is greater than 5 at the following locations'
               ind = getdim(pict, ok)
               for i = 0, nok-1 do print, x[0, i], y[1,i]
             endif
    
           Find the x and y coordinate indices for array, ARRAY, for location IND.
             IND = GETDIM(ARRAY, IND)
               or
             ss = size(array)
             if SS[0] gt 0 then IND = GETDIM(SS[1:SS[0]], IND, /DIMENSIONS) else IND=0
    
    
     MODIFICATION HISTORY:
           Written by:  L. P. Mix, November 16, 2004
    

    (See ../pfidl/pfidl_2d/getdim.pro)


    GET_ARRAY

    [Previous Routine] [Next Routine] [List of Routines]
       this function returns an array from a structure
       Format: get_array(structure, space [, block] [, label= lab] [, /ALLDATA ] )
       where: 
              structure - IDL structure name or structure array number
                          type must be 1, Field
                                       2, Particle
                                       3, Grid
                                       8, Finite Element Time Sliced
                                       9, Finite Element
        Note:  Type 8 and 9 data requires that the ALLDATA keyword is set
               If not set, it will be set silently.
                                       
              space - if not zero indicates spatial dimension desired, if 
                      negative indicates field data and attribute data.
              block - indicates block - not used for particle data
              label - attribute label or block label associated with this data
              alldata - If set all blocks will be returned in a linear array.
                        If ALLDATA is set, then label will be for block 1.
                        If ALLDATA is undefined, and the number of blocks is 
                          greater one, and BLOCK is undefined, then ALLDATA =1
                        ALLDATA is set for type 8 and type 9 data.
                        The array for type 9 data is [num_nodes, num_times]
        example:
         make a contour plot of field data in structure, fld1
    
         contour, get_array(fld1,-1), get_array(fld1, 1, l=xl), $
           get_array(fld1, 2, l= yl), xtit= xl, ytit= yl
    
         note if fld1 is a 3 dimensional array then the above becomes
         k = xx     (define k to be the appropriate location)
         a = get_array(fld1,-1)
         contour , a(*, k, *) , get_array(fld1, 1, la=xlab), $
           get_array(fld1, 3,la=ylab), xtit = xlab, ytit = ylab
    

    (See ../pfidl/pfidl_2d/get_array.pro)


    GET_MAXSTR

    [Previous Routine] [Next Routine] [List of Routines]
         This function returns the maximum number of structure arrays
         format: number = get_maxstr()
    
         NOTE:  The last two arrays are used by some procedures as work arrays
    

    (See ../pfidl/pfidl_2d/get_maxstr.pro)


    GET_STR_VALUE

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           GET_STR_VALUE
    
     PURPOSE:
           Get field values at points 
    
     CATEGORY:
           Input/Output
     CALLING SEQUENCE:
           GET_STR_VALUE, A [, FLD] [, KVALUE1] [, VALUE1] [, TRANSPLOT = transplot]
                      [, INDEX = index] [, KINTEGRATE = kintegrate] 
                      [, XARRAY = xarray] [, YARRAY = yarray]
                      [, FARRAY = farray] [, NFARRAY = nfarray]
     
     INPUTS:
           A     IDL field structure (a.type = 1) or QS array number
           FLD   Field or attribute parameter to be plotted.
           Note: FLD may be positive or negative; FLD = -(abs(FLD))
           Note: If FLD is an array, the square root of the sum of 
                 the squares will be used.
           Note: If A has only one attribute (such as an image or a charge density);
                 the this parameter can be omitted.
           KVALUE1
                 If FLD is a two dimensional field then this value is ignored.
                 If FLD is a three dimensional field then this value
                   indicates the coordinates which are fixed for the two
                   dimensional plots.
                   For 3D plots, x and y are chosen according to:
                      x= (kvalue1 mod 3)+1 and y = (kvalue1+1) mod 3 + 1
           VALUE1
                 If FLD is a two dimensional field then this value is ignored
                 If FLD is a three dimensional field then this value
                   indicates the coordinate value for the fixed dimension in
                   the two dimensional plots. Linear interpolation is used
                   according to the value of VALUE1. If VALUE1 has two elements
                   the average value over the interval is used.
             Note: If INDEX keyword is set, the units are taken as array indices
                   which range from 1 to the maximum value.
             Note: If the two elements of VALUE1 span a block boundary, then only
                   the values in the block containing the midpoint will be used.
                   If the midpoint falls on a block boundary, then the result is 
                   probably not what you want!!
     KEYWORD PARAMETERS:
           TRANSPLOT-If present and not zero, interchange ordinates and abscissa
                     Default is a right hand coordinate system.
           INDEX   - If present and not zero, then the units of VALUEi will be
                     taken as indices of of the field array. Default INDEX = 0 
                     Care should be exercised with multiple block data.
           KINTEGRATE - If present and not zero, integrate the slice rather than 
                     average over the extent of value1(0) to value1(1).
                     The integral will be performed between value1(0) and value1(1)
                     If integrate = 1, a simple integral
                     If integrate = 2, a x dx integral
                     If integrate = 3, a x^2 dx integral
                     Limitations:
                         Data must have a single block
                         Two values of value 1 must exist
    
           XARRAY, YARRAY - Abscissa and ordinate values for the array, FARRAY
           FARRAY   - Values of the field at the coordinates(xarray, yarray)
           NFARRAY  - Elements are 0 or 1 depending on whether FARRAY has valid data.
                               
     OUTPUTS:
           FARRAY and NFARRAY are returned for the input values of XARRAY and YARRAY
    
     EXAMPLE:
           Determine the values of the field in str 4 at the points (x, y) = 
             (3, 4), (4, 5), (5, 6) for a z value = .35.  Store the values in val.
             get_str_value, 4, 3, .35, xar= [3, 4, 5], yar = [4,5,6], far = val
    
     MODIFICATION HISTORY:
          Original version, L. P. Mix, March 16, 1998
    

    (See ../pfidl/pfidl_2d/get_str_value.pro)


    GET_SWEEP

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           GET_SWEEP
    
     PURPOSE:
           Measure the spacing of a comb on the image.
           Image should be rotated using ALIGNSTR before using this routine.
           NOTE: The Maximum WDF array is used as a work array.
                   
     CATEGORY:
           Graphics
    
     CALLING SEQUENCE:
    
           GET_SWEEP, STR1 [, WDF] [, /HORIZONTAL] [, MINBIN = minbin]
             [, SMOOTH = smooth] [, WIDTH = width] [, DEFLECTION = deflection]
             [,/MANUAL] [, QUIET = quiet] [, _extra= extrastuff][, MEDIAN = median]
    
     where: 
           STR1   - Input Structure
           WDF    - Output Waveform Array
                    Default: WDF = get_maxwdf()-1
           HORIZONTAL - IF set, comb is horizontal
           MINBIN - Minimum size of lineouts used to determine feature size.
                    Default = 0.2 of sweep
                    Actual number will always be odd
           SLOPE  - If set, spacing will use a derivative method for finding peaks.
                    This is most useful if the background has a large variation, 
                    but this can be noiser.  Default is slope = 1
           SMOOTH - Size of Boxcar filter, units of pixels
                    If specified, only one calculation
                    Default = 9 
           MEDIAN - Initial filter to remove some of the film noise.
                    If median less than 3 then no median filter will be done.
                    DEFAULT: MEDIAN = 5
           WIDTH  - Fraction of the fwhm used for actual sweep calibration
                    Default = 100%
           MANUAL - Use the cursor to set the position of the comb.
                    This is useful when the frequency of the comb is low.
           Deflection - Fraction of peak derivative which will qualify for a 
                        change in slope.
                        Default = 0.2 for the peak finder.
           _EXTRA - Keyword parameters for plotfld (Xrange, Yrange, etc)
           QUIET  - If set, minimal output
    	
     OUTPUTS:
           Spacing between peaks is stored in a wdf array.
    
     PROCEDURE:
           0. A median with width MEDIAN is applied to the image
           1. User is asked to indicate the location of the comb on the image.
           2-3. If manual is selected the comb is indicated.
           otherwise:
           2. A MINBIN wide lineout is taken perpendicular to the comb.
           3. The fwhm is calculated. 
           4. Width*FWHM lineout is taken along the comb.
           5. The lineout is smoothed with a width of SMOOTH
     if slope is not set:
           6. Peaks larger than deflection are found
           7. The center of the fwhm is used as the middle of the signal.
           8. The spacing is calculated
           9. The median spacing is used to determine if a peak is missed
     if slope is set:
           6. The derivative is taken.
           7. The derivative is smoothed with a width of smooth
           8. Values of the derivative with absolute values greater than
              DEFLECTION * MAX(Derivative) are found.
           9. Values of zero crossing are determined.
          10. Half periods are determined if deflections have opposite signs.
              Multiple zero crossings are not counted.
              
     EXAMPLE:
           Calculate the spacing of a calibration comb stored in image 1.
              alignstr, 1, 2   ; Rotate the image to insure it is square.
              get_sweep, 2, 1  ; Store the spacing in wdf array 1
              plo, 1           ; Look at the spacing
              ; Calculate the average spacing over the range [10,30]
              dist = ave(1, left = 10, right = 30)
              ; If comb is 4 ns then sweep rate is sw 
              sw = 4e-9/dist & print, 'Sweep Rate =' , sw
    
           Similar to the above but use a quadratic sweep
              COMB = 4e-9  ; set the spacing between marks
              alignstr, 1, 2   ; Rotate the image to insure it is square.
              get_sweep, 2, 1  ; Store the spacing in wdf array 1
              wdfit, 1, 2, /plot, degree = 2, coef = coef
              y = get_array(1, 2) ; retrieve the old y values
              ny = n_elements(y)
              dy = [0, y[1:ny-1]-y[0:ny-2]]
              dy[0]= dy[1]  ; calculate the derivative and pad to have the 
                            ; same number of points
              Note: The fit represents the number of y units between markers
                    The new y axis is the integral of old dy * comb/spacing
                        = TOTAL (dy * comb/poly(y, coef), /cumulative, /double)
              Calculate the new Y-values
              yy = comb*total(dy/poly(y, coef), /cum, /double)
              put_array, work, yy, 2, label= 'Time (s)' ; replace the y-values
    
     MODIFICATION HISTORY:
     	Written by:  L. Paul Mix, June 28, 2000
           Modified by:   L. Paul Mix, August 14, 2001
                          Added peak finder option.
    

    (See ../pfidl/pfidl_2d/get_sweep.pro)


    GET_SWEEP2

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           GET_SWEEP2
    
     PURPOSE:
           Measure the spacing of a comb on the image.
           Image should be rotated using ALIGNSTR before using this routine.
           NOTE: The Maximum WDF array-1 is used as a work array unless WDF is 
                 specified.
                   
     CATEGORY:
           Graphics
    
     CALLING SEQUENCE:
    
           GET_SWEEP2, STR1 [, WDF] [, /HORIZONTAL] [, MINBIN = minbin]
             [, SMOOTH = smooth] [, WIDTH = width] [, DEFLECTION = deflection]
             [, MANUAL] [, _extra= extrastuff]
    
     where: 
           STR1   - Input Structure
           WDF    - Output Waveform Array
                    Default: WDF = get_maxwdf()-1
           HORIZONTAL - IF set, comb is horizontal
           MINBIN - Minimum size of lineouts used to determine feature size.
                    Default = 0.1 of sweep
                    Actual number will always be odd
           SMOOTH - Size of Boxcar filter, units of pixels
                    If specified, only one calculation
                    Default = 7 for a first try and do a second try with 
                              smooth = .375 * (average period)
           WIDTH  - Fraction of the fwhm used for actual sweep calibration
                    Default = 70%
           MANUAL - Use the cursor to set the position of the comb.
                    This is useful when the frequency of the comb is low.
           Deflection - Fraction of peak derivative which will qualify for a 
                        change in slope.  Default = 0.1
           _EXTRA - Keyword parameters for plotfld (Xrange, Yrange, etc)
    	
     OUTPUTS:
           Spacing between peaks is stored in a wdf array.
    
     PROCEDURE:
           0. A median with width 3 is applied to the image
           1. User is asked to indicate the location of the comb on the image.
           2-3. If manual is selected the comb is indicated.
           otherwise:
           2. A MINBIN wide lineout is taken perpendicular to the comb.
           3. The fwhm is calculated. 
           4. Width*FWHM lineout is taken along the comb.
           5. The lineout is smoothed with a width of SMOOTH
           6. The derivative is taken.
           7. The derivative is smoothed with a width of smooth 
           8. Values of the derivative with absolute values greater than 
              DEFLECTION * MAX(Derivative) are found.
           9. Values of zero crossing are determined.
          10. Half periods are determined if deflections have opposite signs.
              Multiple zero crossings are not counted.
              
     EXAMPLE:
           Calculate the spacing of a calibration comb stored in image 1.
              alignstr, 1, 2   ; Rotate the image to insure it is square.
              get_sweep2, 2, 1  ; Store the spacing in wdf array 1
              plo, 1           ; Look at the spacing
              ; Calculate the average spacing over the range [10,30]
              dist = ave(1, left = 10, right = 30)
              ; If comb is 4 ns then sweep rate is sw 
              sw = 4e-9/dist & print, 'Sweep Rate =' , sw
    
     MODIFICATION HISTORY:
     	Written by:	L. Paul Mix, June 28, 2000
    

    (See ../pfidl/pfidl_2d/get_sweep2.pro)


    GET_VALID_STRUCTURE

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           GET_VALID_STRUCTURE
    
     PURPOSE:
           Determine if a variable is a valid structure or a valid structure
             array number and return it to the calling program
           Error messages can be make to reflect the calling program.
             
     CATEGORY:
           Utility
    
     CALLING SEQUENCE:
    
           Structure = GET_VALID_STRUCTURE(STR, Call_Prog, LCSTR= lcstr, 
                                     IERROR = ierror)
        Where:
            STRUCTURE - A structure if command is successful
                        0 if STR is not a structure or a valid structure array 
                          number.
            STR       - A structure or a structure array number or a string which
                        matches uniquely a structure comment.  If STR is a string,
                        GET_MATCH(STR, /structure) is used.
            Call_Prog - Name of the calling program.
                        This will be printed if an error occurs.
                        Default: Call_Prog = 'GET_VALID_STRUCTURE'
            LCSTR     - Structure flag if no errors
                        0 if STR is not a valid structure
                        Note: 0 is returned if STR is a valid structure array #.
                        1 if STR is a valid structure
            IERROR    - Error flag
                        0 indicates no errors
                        1 error, STR is undefined or STR is not a structure, or 
                          STR is not a valid structure array number
     EXAMPLE:
           Check FIELD and return it as a structure f_str.  
           Use the variable, lc, to return 1 if FIELD is a structure.
           If an error occurs, label the command with 'PLOTFLD'
             f_str = GET_VALID_STRUCTURE(FIELD, 'PLOTFLD',lcstr = lc, ier = ier)
    
    
     MODIFICATION HISTORY:
           Written by:     Paul Mix, Feb 20, 2002
    
    

    (See ../pfidl/pfidl_2d/get_valid_str.pro)


    HISTS

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           HISTS
    
     PURPOSE:
           Generate a histogram for the waveform array amplitudes.
             This procedure uses the IDL procedure, HISTOGRAM
    
     CALLING SEQUENCE:
    
          HISTS, STR [, WDF] [BINSIZE = binsize] [, NBINS = nbins] 
                 [, MAXIMUM = maximum] [, MINIMUM = minimum] [, /PLOTIT ]
                 [, VECTOR = vector]
                 [, XRANGE = xrange] [, YRANGE = yrange] [, ZRANGE = zrange]
                 [, REVERSE_INDICES = reverse_indices] [, LOCATIONS = locations]
    
     
    
     INPUTS:
           STR;   Input structure or structure array to be analyzed
                  Structure must be type 1 or type 8
    
     OPTIONAL INPUTS:
           WDF:   Output WDF array
                   Default:  WDF = GET_MAXWDF()-1
            Note:  X values are the median values for LOCATIONS
                   IDL histogram uses the minimum value of each bin and these 
                   values are returned in LOCATIONS.
                   Additional Zeros are added to the return from HISTOGRAM to 
                   allow a nice graph with psym= 10
    	
     KEYWORD PARAMETERS:
           Note:  Some of the defaults are set by HISTS
    
           BINSIZE: Size of BINS
           NBINS:  Number of bins
                   Default: NBINS = (NPOINTS/50 + 2) < 1000
                     where NPOINTS = the number of points in the WDF array
           MAXIMUM: Maximum value to consider for the histogram.  This value is
                    increased by 1.0e-6 before being passed to histogram.
              Note: MAXIMUM is ignored if both BINSIZE and NBIN are specified.
              Default: MAXIMUM = MX(WDF1)
           MINIMUM: Minimum value to consider for the histogram.
               Default:  MINIMUM = MN(WDF1)
           VECTOR:  If the number of vectors is greater than 1, VECTOR will 
                    specify the desired vector.
                    Default: VECTOR = 1
           PLOTIT:  If set, WDF will be plotted.
                    "plo, wdf, psym= 10"
       The following "RANGE" keywords apply only to single block data:
           XRANGE:  If two values are provided, only ordinates whose abscissa are 
                    in the specified range are included in the histogram.
                    At least two values must be provided.
                    If there are less than two valid ordinate values, the histogram 
                    will not be calculated.
           YRANGE, ZRANGE: Same as XRANGE for the second and third dimensions.
    
     The following are output if a variable is provided.
           REVERSE_INDICES: See HISTOGRAM for explanation
               Note:  Multi-block structures will NOT produce valid XYZ indices 
                      from REVERSE_INDICES, but HISTS will be valid.
                      Single block structures can use GETDIM to convert the linear
                      index to XYZ indices.
           LOCATIONS: BIN boundaries
                      If H = getyf(WDF2) then H[i] is the number of values, VAL, 
                      which satisfies: LOCATIONS[i] less/equal V less LOCATIONS[i+1]
              Note:  LOCATIONS will be returned, but cannot be set.
    
     OUTPUTS:
           WDF array with the histogram distribution function
    
     OPTIONAL OUTPUTS:
           REVERSE_INDICES and LOCATIONS may be returned.
    
     PROCEDURE:
           This procedure uses the IDL procedure: HISTOGRAM
    
     EXAMPLE:
           Get a histogram of the amplitude of structure array 3 and store it in 33
              HISTS, 3, 33
    
           Calculate the histogram of the amplitude of structure array 5 between 
             X-values of 500E3 and 2E6 with a bin size of 1E5.  Store the result in 75
             and plot the histogram.
             HISTS, 5, 75, min = 5e5, bin = 1e5, max = 2e6, /plotit
    
           Determione the X and Y locations of the values of the structure, intensity,
           between 10 and 12.
              hists, intensity,rev = r, min = 10, max = 12, nbin = 1
              ind = r[r[0]:r[1]-1]  ; get the indices for the first bin
              xyzloc = getdim(get_array(intensity, -1, 1), ind)
              
           Note: xyzloc contains the XYZ locations for the desired intensity. 
                 INTENSITY must be a single block array with no ranges provided.
           To plot the points over the image:
              plotstr, intensity, cn=2
              x = (get_array(intensity, 1)) [zyzloc[0, *]]
              y = (get_array(intensity, 2)) [zyzloc[1, *]]
              mksymbol, 'star'
              plots, x, y, psym=8, color=6
    
     MODIFICATION HISTORY:
           Written by:     L. P. Mix, Jr., March 30, 2005
    
    

    (See ../pfidl/pfidl_2d/hists.pro)


    I2S

    [Previous Routine] [Next Routine] [List of Routines]
     This function puts a structure into the qs structure common.
     Formmat:  i2s, structure, i, no_copy = no_copy
       where:  structure is the structure to be stored in a sturcture array
               i is the structure array number
              no_copy is an optional keyword
                     if set then structrue is undefined after the command
                     if not set then structure is not affected
               
     Example:
        Store structure ff into the qs structure common at location 2
            i2s, ff, 2
    

    (See ../pfidl/pfidl_2d/i2s.pro)


    IMAGE

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           image
    
     PURPOSE:
           Generate an image file from data which has a reflection plane or 
             has periodic boundaries.
           The data must be two dimensional or three dimensional with a degenerate
             dimension and have a single attribute.
    
     CATEGORY:
           Math 
     CALLING SEQUENCE:
           IMAGE, STR1 [, STR2] [, REFLECTION = reflection]
                  [, PERIODIC = PERIODIC] [, VALUE = value] [, /INVERT]
                  [, NPERIODS = NPERIODS] [, CLABEL = clabel] [, /AGAIN]
     INPUTS:
           STR1:    Structure array or array number of the first structure
                    
     OPTIONAL INPUT:
           STR2:    Array number or structure array for the result,
                    if not specified the image is stored in STR1 (the first array)
            Note:   If str1 is an array number then str2 will be an array number.
                    If str1 is an array, then str2 will be an array.
     KEYWORDS:
           REFLECTION : If present must equal to +/- 1, 2, or 3.
                        + indicates maximum value; - indicates minimum value
                        for the reflection.
                        1, 2, 3 indicates coordinates 1, 2, or 3
           VALUE      : If a different value is required for the reflection, 
                        value is used to specify this point. Value must be greater
                        than the maximum spatial value of the data or less than
                        the minimum to avoid multiple values at a point.
                NOTE: For particle data, value should be defined.
           INVERT     : If present and not zero, multiple the field values by -1.
           PERIODIC   : If present must equal to +/- 1, 2, or 3.
                        1, 2, 3 indicates coordinates 1, 2, or 3
                        Current version uses abs(periodic)
                        Single block periodic will remain single block
           NPERIODS   : Number of replications for the periodic data, default = 1
                        Note: NPERIODS =1 for multiple block field data.
           AGAIN      : If present and not zero, all parameters will be the same
                        as the last call to IMAGE
             NOTE: This means all other parameters are ignored
           CLABEL:  Optional label for the combined structures.
     OUTPUTS:
           NONE    The composite image is stored in a structure array 
                     in the common block
     RESTRICTIONS:
           STR1 array must be defined and have valid data
           If a structure has three dimensions, one of them must be degenerate.
           The number of vectors or attributes must be 1, ie scalar field.
     EXAMPLES:
           Assume a field structure in 2 and conductors in 1; generate a 
             a reflection about the positive y value in both.
               IMAGE, SLICE (2, 1), 3, reflect= 2 ; slice will get the r component
           or 
               PLOTSTR, 2, 1, /quiet      ; select the r component of the field
               IMAGE, 82,3, reflect = 2      ; reflect the field
           and
               IMAGE, 1, /again          ; reflect the conductors
           Reflect structure array 2 about the maximum y value and store in 
             array 3
                   IMAGE, 2, 3, reflect = 2
           Reflect structure array 2 about the minimum Z value and store in 
             array 4, and invert the field 
                   IMAGE, 2, 4, reflect = -3
           Reflect structure array 5 about the r= 0 value and store the result in 
             array 4
                   IMAGE, 5, 4, reflect = 1, value = 0
           Replicate structure array 3 about the maximum theta value (dimension 2)
           and store the result in array 
                   IMAGE, 3, period = 2
           Replicate structure array f about the maximum r value and store the
            result in structure, g
                   IMAGE, f, g, period=1
    
     MODIFICATION HISTORY:
          Original version, L. P. Mix, April 21, 1994
    

    (See ../pfidl/pfidl_2d/image.pro)


    INTSTR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
    	INTSTR
    
     PURPOSE:
    	Integrate a two dimensional structure with respect to its first or 
             second dimension.
           Three dimensional data will be reduced to a two dimensional structure.
           Note: Four dimensional data is checked for valid data as closely as 3D
           data.
    
     CATEGORY:
    	Math
    
     CALLING SEQUENCE:
    
    	Structure2 = INTSTR (Structure1, Field, Kvalue1, Value1, Kvalue2, Value2)
    
    
     INPUTS:
    	Structure1: Input this is a multidimensional field type structure.
                         or a structure array numbger
           Field:      Field component to be integrated
           Note: Field may be positive or negative; Field = -(abs(Field))
           Note: If Field is an array, the square root of the sum of
                 the squares will be used.
           Note: If A has only one attribute (such as an image or a charge density);
                 the this parameter can be omitted.
           KVALUE1,2
                 If Field is a two dimensional field then these values are ignored.
                 If Field is a three or four dimensional field then these values
                   indicate the coordinates which are fixed for the two
                   dimensional plots.
           VALUE1, 2
                 If Field is a two dimensional field then these values are ignored
                 If Field is a three or four dimensional field then these values
                   indicate the coordinate values for the fixed dimensions in
                   the two dimensional plots. Linear interpolation is used
                   according to the value of VALUE1. If VALUE1 has two elements
                   the average value over the interval is used.
                 WARNING: If INDEX is specified, VALUE1 will be changed to spatial
                          coordinates using the midpoints of the bins.
    
     KEYWORDS:
           OVERPLOT: If overplot is not zero and kvalue1,2 is undefined, the 
                     values will be taken from the last plot.
           BLOCK   : If the field is multi-block, BLOCK can be used to specify
                     one or more blocks to be sliced.  BLOCK is an array of one
                     or more values.
           INDEX   : If present and not zero, then the units of VALUEi will be
                     taken as indices of of the field array.  Valid values are
                     1 to the maximum number of values in KVALUEi.
                     Care should be exercised with multiple block data.
                 WARNING: If INDEX is specified, VALUE1 will be changed to spatial
                          coordinates using the midpoints of the bins.
           XINTEG  - Integrate the field variable with respect to the abscissa 
                     value (x) according to the following values:
                     If XINTEG = 0, do nothing.
                     If XINTEG = 1, integrate f(x, y) dx
                     If XINTEG = 2, integrate f(x, y) x dx
                     If XINTEG = 3, integrate f(x, y) x^2 dx
                     If XINTEG = string, integrate f(x,y)* g(x) dx
                       dx is the spacing between abscissa values.
                       and g(x) = string where string is any function of x.
                     examples are: string = 'sin(x)'
                                   string = 'x*sqrt(x)'
                                   string = 'my_function(x, 4.5)'
            Note: Either x or y may be used in the function call in the string
                  ie: flag = 'sin(x)' gives the same answer as flag = 'sin(y)'
                      Both x and y will be set to the integration variable
                      Use chastr to multiply the array by coordinate value.
                        for example: integral(f(x,y) *y*g(x) * dx  
                                     must be done with two calls: intstr and chastr
                  The initial value of the integral is set to 0.0 or 
                       to the value in the WDF array specified by START.
              Default: If yinteg and xinteg are both 0 or undefined, then xinteg =1.
               Note: If two blocks terminate on a third, then the initial value of
                     of the integral at the block boundary is linearly interpolated
                     between the two incomming blocks.
           YINTEG  - Integrate the field variable with respect to ordinate 
                     value (y) according to the following values:
                     If YINTEG = 0 or if XINTEG = [1,2,3], do nothing.
                     If YINTEG = 1, integrate f(x, y) dy
                     If YINTEG = 2, integrate f(x, y) y dy
                     If YINTEG = 3, integrate f(x, y) y^2 dy
                     If XINTEG = string, integrate f(x,y)* g(y) dy
                       dy is the spacing between abscissa values.
                       and g(y) = string where string is any function of y.
                     examples are: string = 'sin(y)'
                                   string = 'y*sqrt(y)'
                                   string = 'my_function(y, 4.5)'
            Note: Either x or y may be used in the function call in the string
                  ie: flag = 'sin(x)' gives the same answer as flag = 'sin(y)'
                      Both x and y will be set to the integration variable
                      Use chastr to multiply the array by coordinate value.
                        for example: integral(f(x,y) *x*g(y) * dy   
                                     must be done with two calls: intstr and chastr
                     The initial value of the integral is set to 0.0 or 
                       to the value in the WDF array specified by START.
               Note: If XINTEG ne 0 then YINTEG is ignored.
               Note: If two blocks terminate on a third, then the initial value of
                     of the integral at the block boundary is linearly interpolated
                     between the two incomming blocks.
           START     If present this is interpreted as initial values at the lower
                     limit of integration. Start is an integer indicating a WDF 
                     array.  Values are between 1 and maxwdfarray
           REVERSE   If present and not zero, the limits of integration are 
                     reversed. 
           SMOOTH  - If present and not zero, the two dimensional field will be
                     smoothed using a boxcar filter.  The number of cells will
                     be the lowest odd number greater than or equal to the
                     maximum of [3, SMOOTH]
    
     OUTPUTS:
    	Structure is modified to produce a two dimensional structure or 
           a structure with n-dimensions and all but two degenerate
    
     EXAMPLE:
    	Reduce structure f to a two dimensional structure by slicing along
             the second dimension between 0.0 and 0.4 and integrate with respect 
             to x.  Save the magnitude of the integrated field vector in structure g.
           g = intstr (f, [1,2,3], 2, [0.0, 0.4], /xint)
    
           Assume d is a charge density structure with one attribute.  Take a slice 
             at z= 0.25 and store the integral (y dy) in sturcture array 12.
           i2s, INTSTR (d, 3, .25, yint = 2), 12
       i2s, INTSTR(d, 1, 3, .25, yint = 2), 12
       i2s, INTSTR (d, 3, .25, yint = 'y'), 12
    
           Integrate structure array 2, a two dimensional structure, with respect to 
             the first dimension and store the result in st2.
           st2 = intstr(2, /x)
       st2 = intstr(2)
    
           Integrate structure array 2, a two dimensional structure, times the sin
             of the first dimension with respect to the first dimension and store
             the result in st2.
           st2 = intstr(2, xint = 'sin(x)')
       st2 = intstr(2, xint = 'sin(y)')
    
    
     MODIFICATION HISTORY:
     	Written by:	Paul Mix, August 20, 1993
           Added strings for xintet and yinteg, 2/96 lpm
    

    (See ../pfidl/pfidl_2d/intstr.pro)


    JOINSTR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           JOINSTR
    
     PURPOSE:
           Join a field structure array to another field structure array 
             (See UNIONSTR to actually add blocks which overlap.)
             No check is made to verify blocks are consistent.  All of the blocks
             in each structure are simply combined into a common structure.
       Join a particle structure to another particle structure by 
             adding the particles of the second structure to the end of the
             particles in the first structure.
             No check is made to verify attributes are consistent.  All of the 
             attributes in each structure are simply combined into a common 
             structure, but the number of attributes must be the same and
             degenerate dimensions, if any, must be the same.
    
     For both fields and particles structures:
           Store the result in the initial field structure array or 
             another structure array
           All attributes or vector quantities are joined.
           
     CATEGORY:
           Math 
     CALLING SEQUENCE:
           JOINSTR, STR1, STR2,  [, STR3]
     INPUTS:
           STR1:    array number or structure of the first field structure array
           STR2:    array number or structure of field structure to be joined to 
                    the first structure
     OPTIONAL INPUT:
           STR3:    array number for the combination, if not specified the 
                     combination is stored in STR1 (the first array)
     KEYWORDS:
           CLABEL:  Optional label for the combined structures.
     OUTPUTS:
           NONE    The sum is stored in a structure array in the common block
     COMMON BLOCKS:
           COM.DAT  WDF common block 
     RESTRICTIONS:
           STR1 and STR2 array must be defined and have valid data
           STR1 and STR2 must both be field arrays 
           STR1 and STR2 must have the same number of dimensions and attributes
     PROCEDURE:
           Blocks of STR1 are combined with the blocks of STR2
           The combination of blocks is stored in STR3, if specified, or STR1, 
             if STR3 is not specified.
     EXAMPLES:
           Join structure arrays 2 and 3 and store the result in structure 8
                   JOINSTR, 2, 3, 8
           Join structure arrays 3 and 8 and store the result in structure 10
           with a dataset comment, 'Total Charge - Line + Diode'
                   JOINSTR, 3, 8, 10, c=  'Total Charge - Line + Diode'
     MODIFICATION HISTORY:
          Original version, L. P. Mix, March 8, 1994
          Modified to include get_valid_structure()
          Modified to join particle structures, January 6, 2004
    

    (See ../pfidl/pfidl_2d/joinstr.pro)


    KILL_PART

    [Previous Routine] [Next Routine] [List of Routines]
     function kill_part
     Return the location of killed particles or filter killed particles.
    
     format kill= kill_part(str [, filter = filter] [, ALLORBITS = allorbits] )
      where: 
         kill   - a structure of the parameters for killed particles
         str    - particle structure or structure array number
         filter - If present, killed particles will be filtered according
                  to the value of filter and the entire trajectories returned in 
                  kill.  The form of filter is similar to w1 in plotpar.
                  FILTER must have 3 elements ie. filter = [A, B, C]
                  where A is the quantity, and B and C are the min and maximum
                    values of the quantity. A positive indicates spatial dimensions,
                    and A negative indicates attribute quantities. 
         allorbits - If all the particles in str are known to be killed particles
                     and the user only wants the endpoints, then all orbits 
                     will select the endpoints of all orbits.
         NOTE:     Filter is ignored if allorbits is set.
      example:
      plot the location of killed particles from the particle structure, str
         in a z-r plot
      plotpar, kill_part(str), 3, 1
      
      plot the trajectories of all particles which die in the first dimension
         range [0, .1] in a z-r plot
           s = kill_part(str, filt=[1, 0, .1])
           plotpar, s, 3, 1, /follow
    
      plot the endpoints of the above subset of the particles in r/z
           plotpar, kill_part(s, /all), 3, 1
    

    (See ../pfidl/pfidl_2d/kill_part.pro)


    LINEOUT

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           LINEOUT 
    
     PURPOSE:
           Generate lineouts from any 2 or 3-D structure
           Procedure will generate a lineout with arbitrary directions and 
             number of points.
           Lineouts must have a minimum of 3 values.
           Distances are slant distances from one end point or X, Y, Z value
           A single lineout is produced by each call to LINEOUT
    
     CALLING SEQUENCE:
    	LINEOUT, STR , WDF 
       where:
           STR   - Structure array number or actual structure
                   Structure must be a type 1 field type structure
                   Note: Data will not be transposed.
           WDF   - WDF array number to store the lineout. Default is 1.
                   WDF can be set manually.
             
     REQUIRED KEYWORD PARAMETERS:
           STARTPOINT: Point for start of the lineout
                       STARTPOINT must have as many elements as the dimensions of
                       the structure and be within the data range of the structure
           DIRECTION:  Direction for the lineout 
                       Direction cosines for the lineout
                       (Not required if ENDPOINT is specified)
           ENDPOINT:   End point for the lineout
                       (Ignored if DIRECTION is specified)
    
     REQUIRED KEYWORD PARAMETERS:
           TOTAL_LINE: If set, all points along the lineout path in both directions
                       are returned.  Minimum X value will be the first point.
                       Default = 0 ; Only the points between the two points or from
                         the first point to the end of the data are returned.
    	ABSCISSA:   If set to 1, 2 or 3 then X, Y, or Z will be used as the 
                       abscissa of the lineout.  
                       Default is SQRT(DX^2+dy^2+dz^2)
           NPOINTS:    Number of points.  Default is 2*max(128, nx, ny, nz)
                       where nx, ny, nz are then total number of points in each
                       direction.
           MISSING:    WDF array values are preloaded with this value.  Values
                       not found retain this value.
    
     EXAMPLE:
    	Take a series of lineouts from structure array 3 and store the lineouts
             beginning in wdf array 11 from [0,0,0] to [1,1,1].
               LINEOUT, 3, 11, start =[0,0,0], endpoint=[1,1,1]
    
           Take a series of lineouts from structure array 4 and store the lineouts
             beginning in wdf array 11 from [0,0,0] to [1,1,1] but extend the 
             lineout in both directions to include the total data extent.  Take 
             1000 points
               LINEOUT,4,11,start=[0,0,0],endpoint=[1,1,1], /total, np=1000
           LINEOUT,4,11,start=[0,0,0],direction=[1,1,1]/sqrt(3.),/total,np=1000
    
    
     MODIFICATION HISTORY:
     	Written by:	L. P. Mix, May 9, 2003
    

    (See ../pfidl/pfidl_2d/lineout.pro)


    LINSTR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           LINSTR
    
     PURPOSE:
           Generate lineouts from any 2-D structure
           Single block data generally uses the actual data for the lineout.
           Multiple block data is put on a uniform grid with 1 pixel resolution.
           Procedure will generate lineouts and display them. Lineouts use
             the existing grid in one direction. The X or Y values are used
             depending on which direction provides the most values between the
             designated end points. Lineouts must have a minimum of 3 values.
             Distances are slant distances from one end point.
           When designated, the lineouts will be stored in WDF arrays.
           Horizontal and Vertical lineouts require a single point.
           A preview gives lineout before storage. A preview will be generated
             whenever the mouse moves in the window and one point has been
             selected for a general lineout or if no points are selected for a
             vertical or horizontal lineout.
           Note: Some time is required to calculate a preview frame. All events
                 generated while the preview frame is generated are deleted; be
                 sure the mouse clicks are acknowledged before proceeding.
           Mouse buttons are mapped to widget buttons, cursor must be in the
             DRAW area of the main widget for the following mouse commands.
              Left Button   = Set Value
                  Note: A carriage return in the data field will also set the value.
              Middle Button = Accept/Save
                 (current designated lineout will be saved)
              Right Button  = Reset All Points
                 (All points will be undesignated)
              Note: If a the last point required to define a curve is selected
                    more than once, the previous "last point" is replaced.
           Set Point Buttons: These perform the same function as a  in either
                              the X or Y windows above the buttons.
    
     CALLING SEQUENCE:
       LINSTR, STR [, WDF] [, X, Y]
       where:
           STR   - Structure array number of a two dimensional structure or
                   a slice from three dimensional structure.
                   The structure should be single block for best results. Multi-
                   block structures will be put on a uniform 256 by 256 grid.
                   To use an interpolation with N elements use:
                     PLOTSTR, STR, NFARRAY = N, RESULT = STR2
                     LINSTR, STR2, wdf
                   Note: Data will not be transposed.
           WDF   - WDF array number to store the lineout. Default is 1.
                   WDF can be set manually.
                   Note: WDF must be specified if X and Y are specified.
    
           X, Y  - 2N X-values and 2N Y-values if neither horizontal nor verticle
                   is set. Lineouts of arbitrary pairs of points may be obtained
                   directly where N is the number of lineouts.
       or
           X     - N values corresponding to Y or X values if horizontal or verticle
                   is set, respectively.
    
     KEYWORD PARAMETERS:
           XVALUE: This keyword is an alternate way to specify X above.
                   Note: XVALUE must be specified if wdf is not specified.
                   Note: XVALUE is ignored if X is specified.
           YVALUE: This keyword is an alternate way to specify Y above.
                   Note: YVALUE is ignored if Y is specified.
           ORDERX:     If set, lineouts are from Minimum X to Maximum X.
                       Default = 0 ; from first point to second point
           Horizontal: If present and not zero, then a full width horizontal
                       lineout is taken. Can also be set manually.
                       Only one point must be designated.
           Vertical:   If present and not zero, then a full height vertical
                       lineout is taken. Can also be set manually.
                       Only one point must be designated.
           Preview:    If present and zero, no preview will be generated.
                       If positive, preview will have a fixed scale equal to the
                         total range of data.
                       If preview has two elements, these will be used as the
                         y-range of the preview frame.
                       Default is preview = -1 => Auto scale preview.
            Note: Preview frame may be resized.
           PXRANGE:    Xrange for the preview frame.
                       Default is the range of data.
           Width:      In current version, a horizontal or vertical lineout will
                       use the actual specified width at each Y or X value.
                       Arbitrary Slope Lineout
                       The width is modified to
                          delta_x = W/sin(SlopeAngle)  or
                          delta_y = W/cos(SlopeAngle)
                       All values are taken at a fixed value of X or Y.
           Median:     If set, and Width is not zero, then a median filter
                       will be taken.
           Integral:   If set, and Width is not zero, then an integral
                       will be taken between lower and upper limits.
           WDFarray:   Array of WDF arrays where lineouts are stored.
                       If no values are stored, then WDFarray = 0
           Xonly:      Return the abscissa values only not the length along the
                       lineout, ie the wdfarray will be amplitude vs x axis value.
                       Xonly is ignored if delta X/max(X)< 1e-4
           Yonly:      Return the ordinate values only not the length along the
                       lineout, ie the wdfarray will be amplitude vs y axis value.
                       Yonly is ignored if delta Y/max(Y)< 1e-4
           SLOPEAngle: Angle in degrees of the slope of the last lineout
                       Result of arc tangent with two arguements.
           CPRINT:     If set, print the dataset comment for each lineout
                       to the terminal
           IFLAG:      If set, the first point will be set to the nearest X or Y
                         value.  If width is not zero, spatial averaging will
                         still occur.
                         IFLAG = 1, First point set to nearest X value
                         IFLAG = 2, First point set to nearest Y value
                         IFLAG = 3, First point set to nearest X and Y value
           PLAST:      Coordinates of first point of the last lineout selected
           QLAST:      Coordinates of second point of the last lineout selected
           _EXTRA:     Any valid keyword for plotfld. The array for the lineout
                       is generated with the following command and this plot is
                       used for the image:
              PLOTFLD, str, nfarray=256, xarray = x, yarray = y, farray = array, $
                     nlev = 29,  _extra = extrastuff
             Note: nfarray is ignored with single block data
     EXAMPLE:
       Take a series of lineouts from structure array 3 and store the lineouts
             beginning in wdf array 11.
               LINSTR, 3, 11
    
       Take a series of lineouts from structure array 3 and store the lineouts
             beginning in wdf array 11; Set the preview to fixed scaling.
               LINSTR, 3, 11, /preview
         or    LINSTR, 3, 11, /prev
    
           Take a series of lineouts from structure array 1 and plot the lineouts
             12 to a page.
               LINSTR, 1, wdf= wdf
               plo, wdf, g = 12
    
           Take a radial lineout from (0, 0) to (3, 3) and store the result
             in wdfarray 4 from structure 82
    
             LINSTR, 82, 4, [0, 3], [0, 3]
    
     MODIFICATION HISTORY:
       Written by:  L. P. Mix, August 27, 1996
                    Added width options to all lineout types, March 16, 2005
    

    (See ../pfidl/pfidl_2d/linstr.pro)


    LOGSTR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           LOGSTR
    
     PURPOSE:
           Take the log of values in a structure array.
    
     CATEGORY:
           Utility
    
     CALLING SEQUENCE:
           LOGSTR, STR_IN [, STR_OUT]
     INPUTS:
           STR_IN:   Structure array number or structure array to take the logarithm
                     STR_IN may be a search string for a structure array.
           STR_OUT:  Structure array number or structure array for the smoothed
                     result.   If STR_OUT is present but does not have a valid 
                     value, the default value is (get_maxstr()-1)
                     If STR_IN is a structure, then 
                       If arg_present(STR_OUT) then STR_OUT = LOG(STR_IN) else
                         arg_present(STR_IN) then STR_IN = LOG(STR_IN) else 
                         LOG(STR_IN) is stored in (get_maxstr()-1)
                     If STR_IN is a string or number, then LOG(STR_IN) will
                       be stored in a structure array.
                       If STR_OUT is present, but undefined then it will be set.
                       If STR_OUT is defined, then that will be used if valid or
                         STR_OUT will be set to (get_maxstr()-1)
                       If STR_OUT is not present, then the result is stored in
                         STR_IN. 
     KEYWORD PARAMETERS:
           MINIMUM:  Used to determine the minimum value for the logarithm.
                 Note: In the case of a relative minimum, the maximum is the 
                       maximum for all times unless TIME is set.
                     LOG_MIN = MINIMUM
                       IF (LOG_MIN LT 0.0 or LOG_MIN GE 1) then
                           MINVAL = ABS(LOG_MIN)
                       IF (LOG_MIN GT 0 AND  LOG_MIN LT 1) then
                           MINVAL = LOG_MIN*MAX(abs(field_value))
                       unless RELATIVE = 0
           NATURAL:  Natural LOG (ALOG)
                     IF NATURAL = 0, base 10 log (ALOG10)
                     DEFAULT: NATURAL = 1
                     Labels will be LOG for Natural Log and LOG10 for base 10
           RELATIVE: If set to zero, then MINVAL= ABS(MINIMUM) regardless of value
                     DEFAULT:  RELATIVE = 1
                     If MINIMUM in the range(0,1) and RELATIVE = 1, then
                        MINVAL = LOG_MIN*MAX(abs(field_value))
           TIME:     Ignored unless type 9 structure
                     If set, and minimum is in the range (0,1), then 
                     the minimum will be set differently for each time step.
           SCALE:    If not equal to zero, values will be multiplied by SCALE 
                     before the LOG is taken.
                        Vector = SCALE * Vector
                     DEFAULT: SCALE = 1
           ABSOLUTE: If set, the absolute value will be taken before taking the log.
                     If set, the order is:
                        Vector = ABS(SCALE*Vector)
           SHOWDEFAULT: Show the default values
           UNSET:    Reset the default values
                     LOG_MIN = 1.0E-4
                     LOG_TYPE= 1 (NATURAL TYPE)
           SETDEFAULT: Make the current values the default values.
    
     OUTPUTS:
           The LOG of the specified structure is returned in STR_IN or STR_OUT
    
     RESTRICTIONS:
           STR_IN array must be defined and have valid data.
            NOTE:  Results with multi block data may not be satisfactory
                   along block boundaries.
    
     TECHNIQUE:
           The data is filtered with respect to the MINIMUM and the appropriate 
           logarithm is taken
    
     EXAMPLES:
           Take the natural logarithm of STR 2 and save it in 3
                LOGSTR, 2, 3
           Take the natural logarithm of STR 2 and save it back in 2
                LOGSTR, 2
           Set the minimum to an absolute value of 1.0e-6
                LOGSTR, -1.0e-6, /set
           Take the logarithm of the density and store it into the same structure 
             array and plot the result
                LOGSTR, 'density'
                PLOTSTR, 'density', cn=2
    
     MODIFICATION HISTORY:
          Original version, L. P. Mix, December 15, 2003
            Based on routine by R. W. Lemke, "make_log_str"
    

    (See ../pfidl/pfidl_2d/logstr.pro)


    MAXSTR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           MAXSTR
    
     PURPOSE:
           Find the maximum of a structure array and the location of that maximum.
           Current version is for type 1 field structures.
    
     CATEGORY:
           Math
    
     CALLING SEQUENCE:
           Field_Max =  MAXSTR (Structure [, Vector]  )
    
     where Field_Maxin is the minimum value of the field. 
    
     INPUTS:
           Structure - Structure array number or idl field Structure.
     OPTIONAL INPUTS:
           Vector    - Vector component for the function.
                       If Vector is an array, the square root of the sum of
                         the squares will be used.
                       If Vector is a single value array, ABS will be applied to 
                         that component. That is if Vector = [2] then 
                         ABS(V2) will be searched.
                       If max(Vector) has a value larger than the number of vector
                         components and dimensions, then Vector = 1+indgen(nvect)
                         where nvect is the number of vector components
                       Default: VECTOR = 1 if number of vectors is 1
                                VECTOR = 99 if number of vectors is > 1.
    	
     KEYWORD PARAMETERS:
           XRANGE    - Range of the first dimension for the maximum search.
                       Default:  All X values
           YRANGE    - Range of the second dimension for the maximum search.
                       Default:  All Y values
           ZRANGE    - Range of the third dimension for the maximum search.
                       Default:  All Z values
           LOCATION  - Position where maximum occurs
           PMAXIMUM  - Same as LOCATION
           MINIMUM   - Maximum val in the range defined.
           PMINIMUM  - Position where MINIMUM occurs.
           IER       - Error parameter
                       Default: IER = 0 ==> No problems 
    
     OUTPUTS:
           The function returns the Maximum of the field structure.
    
     OPTIONAL OUTPUTS:
           Minimum and the locations for the maximum and minimum are returned
    
     EXAMPLE:
           Determine the range of the electric field structure E
             range = maxstr(E, 4, min= emin) -emin
    
     MODIFICATION HISTORY:
           Written by:     L. P. Mix, March 12, 1999
    

    (See ../pfidl/pfidl_2d/maxstr.pro)


    MINMAX

    [Previous Routine] [Next Routine] [List of Routines]
     Name:
           MINMAX
    
     PURPOSE:
           Scan in a PFF file in DO List and determine the range of the
             attirbutes.  All datasets must be of the same type.
     CALLING SEQUENCE:
           Range = MINMAX( Comp [, DatasetMin] [, DatasetMax] [, DatasetStep]
               [, ARRAY = array] [, PRINTIT = printit] [, _EXTRA = extrastuff] ) 
       where:
           Range:    Vector with the maximum and minimum values.
                     If comp is an array then range = range(2, n_elements(comp)]
                     If an error then range = -1
    
           Comp:     Field component: either 1, 2, or 3 for a single
                     component, 0 for all components or -1 for magnitude
                     of a vector
                     Note: If more than 1 components is desired use 0.
           The datasets in the current PFF file are scanned in a Do list
           DatasetMin  \
           DatasetMax   -   DO list for dataset numbers in file
           DatasetStep /
           All parameters have default values.
           Default Values are : DatasetMin =1
                                DatasetMax =ndspff()
                                DatasetMin =1
             If DatasetMax is less than DatasetMin then DatasetMax = ndspff
           ARRAY:    Array of dataset numbers
                     Values allowed are gt 0 and le ndspff()
                     If invalid values are listed, routine returns a -1
           Printit:  If set, values will be printed.
           _EXTRA:   Any valid keywords for READSTR
     Examples:
           Get the max and min of all the datasets in the current file for the
              first vector component.
              val = MINMAX(1)
    
           Get the max and min of all the datasets in the current file for the
              magnitude of vector component.
              val = MINMAX(-1)
    
           Get the max and min of dataset 5 and for every 3 dataset in the
             current file for the third vector component and print the values.
              val = MINMAX(3, 5, 0, 3,/print)
    
           Get all the datasets with 'rho-e'
              val = minmax(0, array= get_dset('rho-e'))
           Note:  DIR command strips spaces to obtain maximum information.
                  DIRPFF, -3 will print the actual comments 3 comments on
                          either side of the current position.
                  so: 'rho-e', 'rho-p', and 'rho    ' will get different datasets.
                    (Trailing spaces on the search string ARE significant.)
           
           Original version by TDPointon. 
           Rewritten Feb 12, 1998 - lpmix
    

    (See ../pfidl/pfidl_2d/minmax.pro)


    MINSTR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           MINSTR
    
     PURPOSE:
           Find the minimum of a structure array and the location of that minimum.
           Current version is for type 1 field structures.
    
     CATEGORY:
           Math
    
     CALLING SEQUENCE:
           Field_Min =  MINSTR (Structure [, Vector]  )
    
     where Field_Min is the minimum value of the field. 
    
     INPUTS:
           Structure - Structure array number or idl field Structure.
     OPTIONAL INPUTS:
           Vector    - Vector component for the function.
                       If Vector is an array, the square root of the sum of
                         the squares will be used.
                       If Vector is a single value array, ABS will be applied to 
                         that component. That is if Vector = [2] then 
                         ABS(V2) will be searched.
                       If max(Vector) has a value larger than the number of vector
                         components and dimensions, then Vector = 1+indgen(nvect)
                         where nvect is the number of vector components
                       Default: VECTOR = 1 if number of vectors is 1
                                VECTOR = 99 if number of vectors is > 1.
    	
     KEYWORD PARAMETERS:
           XRANGE    - Range of the first dimension for the minimum search.
                       Default:  All X values
           YRANGE    - Range of the second dimension for the minimum search.
                       Default:  All Y values
           ZRANGE    - Range of the third dimension for the minimum search.
                       Default:  All Z values
           LOCATION  - Position where minimum occurs
           PMINIMUM  - Same as LOCATION
           MAXIMUM   - Maximum val in the range defined.
           PMAXIMUM  - Position where MAXIMUM occurs.
           IER       - Error parameter
                       Default: IER = 0 ==> No problems 
    
     OUTPUTS:
           The function returns the Minimum of the field structure.
    
     OPTIONAL OUTPUTS:
           Maximum and the locations for the maximum and minimum are returned
    
     EXAMPLE:
           Determine the range of the electric field structure E
             emin = minstr(E, 4, max= emax)
             range = emax-emin
    
    
     MODIFICATION HISTORY:
           Written by:     L. P. Mix, March 12, 1999
    

    (See ../pfidl/pfidl_2d/minstr.pro)


    MULSTR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           MULSTR
    
     PURPOSE:
           Multiply a field structure array to another field structure array 
             or to a constant 
           Store the result in the initial field structure array or 
             another structure array
           All attribute or vector quantities are multiplied.
     CATEGORY:
           Math 
     CALLING SEQUENCE:
           MULSTR, STR1, STR2,  [, STR3]
           MULSTR, STR1, 0, VAR, [, STR3]
     INPUTS:
           STR1:    Structure or structure array number of the first structure
                    The output is the same form as the first structure.
                    If STR1 is an IDL structure and the result is to be saved
                      as an IDL structure in STR3 then the keyword: STRUCTURE
                      must be set and STR3 must be a variable.
           STR2:    Structure or structure array number of the second structure
      or
           0, VAR    Variable or constant to multiply the first structure
                     NOTE: CHASTR may be used.
                           CHASTR, STR1, SCALE = VAR
     OPTIONAL INPUT:
           STR3:    Structure variable or structure array number for the sum
                    If not specified the product is stored in STR1 (first array)
                    The product is in the same form as the input (STR1).
     KEYWORDS:
           STRUCTURE: Optional keyword which must be present if an idl structure
                    is to be saved in the variable STR3. See example.
           CLABEL:  Optional label for the combined structures.
           MASTER:  Optional grid specification for single block, two dimensional
                    data.  Normally this type of data is put onto a uniform grid
                    with a spacing equal to the minimum spacing anywhere for either
                    grid.  If master = 1, the grid STR1 is used for the result;
                    STR2 is interpolated onto the grid of STR1.
                    If master = 2, then STR1 is interpolated onto the grid for
                    STR2 and the result has the same grid as STR2.
                    If MASTER is positive, the master grid will not be changed.
                    If MASTER is negative (or zero), the master grid will be
                    reduced to the region of overlap between STR1 and STR2.
                    For 3-Dimensional or multi-block data MASTER must be 1 or 2.
                      The data will be put onto the grid of either the first or
                      second structure array grid.  Missing values are set to zero.
           CUBIC:   If set a cubic interpolation will be used to match single
                    block data on different grids
     OUTPUTS:
           NONE    The quotient is stored in a structure array in the common block
     COMMON BLOCKS:
           QSCOM.DAT QSSTRCOM.DAT
     RESTRICTIONS:
         If not a single block of data and two dimensions then:
           STR1 array must be defined and have valid data
           STR2 or 0 and a Variable must be defined
         If master is specified, there are no additional restrictions.
           otherwise:
         If not a single block of data and two dimensions then:
           STR1 and STR2 must both be field arrays and have the same number
             of vector components.
           The SIZE of STR1 and STR2 must be the same
           The values of the spatial coordinates must be equal to about 
           3e-5(ie.- max(abs(difference))/max(value) lt 3.1e-5 )
           The check on spatial coordinates is done globally rather than 
             on a block by block basis.
           If a structure has three dimensions, but is degenerate in one of them
             that axis need not be equal.
         If a single block in two dimensions then the data will be interpolated to
           a common spatial scale using a cubic bilinear interpolation.
     PROCEDURE:
           If STR1 or STR2 is a type 8 structure.
           If str.v1 has the same number of elements as str.v2 then:
             MULSTR returns str1.v1*str2.v1 or str1.v1*VAR
               with the spacial values from STR1.
             If str1.nvect is lt str2.nvect the unmatched vectors from str2 are
               ignored.
    
         For type 1 structures:
           If STR2 is specified:
                Each vector component, of STR1 is multiplied to 
                    each vector component of STR2
           If 0, VAR is specified:
                VAR is multiplied to each attribute of STR1
           In either case, the product is stored in STR3, if specified, or STR1, 
           if STR3 is not specified.
     EXAMPLES:
           Multiply structure arrays 2 and 3 and store the result in structure 8
                   MULSTR, 2, 3, 8
           Multiply the variable OFFSET to structure  array 2 and store the product
           in structure 8
                   MULSTR, 2, 0, offset, 8
           Multiply structure arrays 3 and 8 and store the result in structure 10
           with a dataset comment, 'Total POWER - Current * Voltage'
                   MULSTR, 3, 8, 10, c=  'Total POWER - Current * Voltage'
           Assume f is an idl structure.
                 MULSTR, f, 2 ; Multiply f to Structure array 2 and return the 
                         product as an idl structure in variable f.
                 MULSTR, f, 2, 3 ; Multiply f to Structure array 2 and return the
                         product to structure array 3
                       Note: A warning will be printed. To avoid the warning use:
                               i2s, f, 3 & MULSTR, 3, 2
                 MULSTR, f, 2, g, /s ; Multiply f to Structure array 2 and return 
                               the product as an idl structure in variable g
                      Note: If g is not a variable then the results will be lost.
    
     MODIFICATION HISTORY:
          Original version, L. P. Mix, JULY 15, 1992
    

    (See ../pfidl/pfidl_2d/mulstr.pro)


    PFF_REGRID

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:		PFF_REGRID
     PURPOSE:
    	do density-to-exposure unfold and regridding of scanned PFF image
    	file, and write out a new (smaller) PFF file containing the regridded
    	exposure values. Used as a preprocessor to deal with high-res scanned 
    	data to avoid bogging down Vida.
     CATEGORY:	image pre-preprocessor (scans)
     CALLING SEQUENCE:
    	PFF_REGRID, INFILE [, FITFILE] [, /ZERO_ORIGIN] [,REGRID=regrid]
                  [, XREGRID=xregrid] [, YREGRID=yregrid] [, OUTFILE = outfile]
                  [, /STRUCTURE] [, VALID = valid] [, DEFAULT_VAL = default_val]
     INPUTS:
    	infile	string containing PFF filename to process. User should also
    		provide the extension (.pff, .PFF, etc)
                   Enter 0 or ' ' to use pickfile.
                   If keyword (STRUCTURE) is set, then INFILE is a structure
                     or structure array number.
                   Structure must be a single block, uniform, type 1 structure.
          fitfile	string containing film response filename to use. 
                   Enter 0 or ' ' to use pickfile.
                   Should have been created in WDFIT3
                   Can be pre-loaded with READWD3.
                   Values read will be stored in the WDFIT3 common block.
                   If omitted then current values in the WDFIT3 common block are
                   used.
                   If FITFILE is lt 0 then response is not calculated.
                   and a structure is returned in structure array outfile.
                   (See SCALE_REGRID with C1=[0, 1]
     KEYWORDS:
      STRUCTURE    If set INFILE is a structure or structure array number.
      VALID        Two element vector with minimum and maximum values for
                   the scaling.  DATA values outside these limits will be
                   set to the values of default.
                   Default: VALID = [min(data, max = mdata), mdata]
                   (See: SCALE_REGRID
      ZERO_ORIGIN  if nonzero, specifies that x,y axis values should be offset
    		so that lower left corner of image will be at 0,0.
        regrid     integer >=1 to specify what factor to regrid data by. Note
    		that idl rebin routine is used - averages points. May lose
    		at most regrid-1 of the uppermost rows or columns of scanned
    		data in this process. Equivalent to specifying x_regrid=regrid
    		and y_regrid=regrid.
                   Default value: REGRID = 5
       x,yregrid	integers >=1 allowing independent regridding factors 
    		in the x and y dimensions. 
                   Default value: X,YREGRID = REGRID
       default_val Default values for regrid if infile values are outside the range
                   DEFAULT = [0, value at VALID(1)] 
       OUTFILE     Output file name or a number.
                   If outfile is a number between 1 and get_maxstr(), then the 
                     result will be stored in "outfile" as a structure.
                   Default: 
                     1. Creates a new PFF file in current directory, with 
                        a '_ur' suffix added to root of INFILE if STRUCTURE =0.
                     2. Saves the result in GET_MAXSTR()-1 if STRUCTURE ne 0.
                  
     SIDE EFFECTS:
           If OUTFILE is not a number, then PFF_REGRID creates a new PFF file
           with the as defined by OUTFILE or a new PFF file in current directory,
    	with a '_ur' suffix added to root of filename
     RESTRICTIONS:
    	User should NOT have a file of the same name as the output file in
    	the working directory! Output filename will be modified.
     EXAMPLE:
           Fit film response data and unfold a pff file and write it out with
             a reduction in size of 16 (= 4*4), put (0,0) at lower left corner.
               revida, 0, 1      ; read a vida output file
               wdfit3, 1, /ylog  ; fit the data to a polynomial
               pff_regrid, 0 , regrid = 4, /zero
     
     MODIFICATION HISTORY:
    	Written by Alex B. Filuk, Sandia, 1/17/95
    	ABF (1/25/96) - mods to use readuf3 instead of readpff
           Completely rewritten: lpmix 8/6/98
           Added structure keyword: lpmix 10/9/02
    

    (See ../pfidl/pfidl_2d/pff_regrid.pro)


    PIXPLOT

    [Previous Routine] [Next Routine] [List of Routines]
        read an ascii file of amplitude, x and y values and optionally delta-X and
          delta-Y values. Generate a field type structure of the data.
          blank lines are ignored and lines with less than 3 numbers are ignored.
          TQEDIT can be used to modify/add/delete regions.
        Alternatively, if the plotonly keyword is set a contour pixplot will
          be generated with the data, but no structure will be returned.
    
        CAUTION:
             The TQBUILD code suite is used. Current data in this commmon
               block can be lost.
    
        format: str = pixplot([, fname] [, skip = skip] [, ignore = ignore]
                    [, fast = fast]
                    [, circle = circle] [,xdelta = xdelta] [,ydelta = ydelta]
                    [,nx = nx] [,ny = ny] [,np = np] [, xlog = xlog] 
                    [, ylog = ylog] [, zlog = zlog] [, xrange = xrange]
                    [, yrange = yrange] [, default = default] [, highres = highres]
                    [,xlabel = xlabel] [, ylabel = ylabel] 
                    [, clabel = clabel] [, tlabel = tlabel] 
                    [, plotonly= plotonly] [, levels = levels] [, ccolor = ccolor]
                    [, thermometer = thermometer] [, tparam = tparam]
                    [, Nlevel = nlevel] [, _extra = extrastuff] )
        where
          str     - PIXPLOT data is returned in structure, STR
                  - If an error occurs, STR = 0
          fname   - the file name or a unit number
                    if a file name then the file is opened and closed at the end
                    if a number then the file is read directly
                    if unit is equal to zero or fname is undefined then 
                      pickfile will be used to determine a file
                    if pickfile is called then fname will contain the file name
                      on return from pixplot
                    file should contain data of the form:
                       amplitude xvalue yvalue 
                    or optionally (where absolute values are used for the last 2):
                       amplitude xvalue yvalue deltax deltay
          skip    - If the file has several lines of header information which
                    must be skipped, set skip equal to this number of lines.
                    (DEFAULT: SKIP = 0)
         ignore   - String array. Space is used as a delimiter.  Any nonnumeric 
                    characters to be ignored are listed in ignore. See example.
         fast     - If set polyfillv will be used to determine values; slight
                      errors can occur
         circle   - If set, an ellipse is drawn around the specified points
                    Default is CIRCLE = 0.  A rectangle is drawn
         Xdelta   - Default deltax value if not listed in the file
                    Default is 0.5; must be greater than zero.
         Ydelta   - Default deltay value if not listed in the file
                    Default is 0.5; must be greater than zero.
         nx, ny   - number of resolution elements in the X and Y directions
                    Default = np > 3
         np       - Default for nx and ny if not specified.
                    Default value is 250 or 1250 depending on HIGHRES
         highres  - If set, Default value of np is 1250 otherwise np = 250
                    If highres is set then fast is set.
                    If np is specified, this keywork is ignored.
         lowres   - If set, Default value of np is 50 otherwise np = 250
                    If np is specified, this keywork is ignored.
         xrange   - Range of x-Values
         yrange   - Range of y-Values
         default  - Default value for the two dimensional array 
                    Default = 0.0 unless zlog is set.
         xlog     - If set, X-data is the log of the actual data
         ylog     - If set, Y-data is the log of the actual data
         zlog     - If set, Z-data is the log of the actual data
         xlabel   - X-label for the data- Default ='X Axis'
         ylabel   - Y-label for the data- Default ='X Axis'
         clabel   - Comment label for the dataset- Default ='PixPlot Data'
         tlabel   - Type label for the dataset- Default ='PixPlot Data'
         plotonly - If set, no structure is returned but the PixPlot data is
                    plotted in a contour plot.
      The following keywords are used only for PLOTONLY
         nlevel   - Number of contour levels. Default is 20
         levels   - Contour level values, These will be sorted.
                    If levels has <2 elements, the actual values will be returned.
                    If levels has more than 1 value, these values will be used for
                      the contour plot and nlevel will be set to this number
                    Default levels:
                    levels = vmin + (vmax-vmin)/nlevel*findgen(nlevel)
         ccolor   - C_color keyword values for the contour plot
                    If ccolor has <2 elements, the actual values will be returned.
                    If ccolor has more than 1 value, these values will be used for
                      the contour plot with the c_color keyword.
                    Default levels
                    ccolor = 9+round((!d.table_size-11)*(1+indgen(nlevel))/nlevel)
                    Note: If Ccolor is passed and levels are passed, both will be
                          sorted.
                    Note: If the number of elements in CColor is more than levels,
                          they will be truncated.  If the number of levels is less,
                          the CColor values will be replicated.
        THERMOMETER- If keyword is set a thermometer will be generated
                     with the contour plot.
                     Default IDL margins are [10, 3] for x and [4, 2] for y
                     If TPARAM does not have a Tag Name beginning with 'CU'
                     then:
                     If no tag names begin with 'H' xmargin will be set to
                       [!x.margin(0), 10]
                       otherwise ymargin will be set to [8, !y.margin(1)]
               Note: xmargin or ymargin passed to plotfld will override
                           these settings.
               Note: If THERMOMETER is a structure, then TPARAM is ignored
                     and set equal to THERMOMETER
           TPARAM  - Structure containing data for the thermometer, Tag names
                     must be valid for the THERMOMETER procedure.
           _extra - Any valid keywords for the plot command
                   Default values for the contour plot are:
                   plot, x, y, /nodata, $
                   xrange = xrange, yrange = yrange, title = clabel, $
                   xlog = xlog, ylog = ylog, xtitle = xlabel, ytitle = ylabel
                   _extra = extrastuff
         Procedure:
           calculate a center and a radius for x and y
           if a log plot:                     for a linear plot:
                center = sqrt((x+dx)(x-dx))      center = x
                radius = log((x+dx)/center)      radius = dx
           generate the region:
             circle set: tqcond,centerx+radx*cos(angle), centery+rady*sin(angle)
                  where angle is an array of angles between [0 , 2pi]
             circle not set: 
                  xx = [centerx-radx, centerx+radx, centerx+radx, centerx-radx, $
                       centerx-radx]
                  yy = [centery-rady, centery-rady, centery+rady, centery+rady, $
                       centery-rady]
                  tqcond, xx, yy
           edit the regions then fit to a grid and edit again if necessary
           fill the regions and condstruct a structure.
         Example:
           assume a data file containing:
     ;     1 6 6 5 5 
     ;     2 6 6 4 4
     ;     3 6 6 3 3
     ;     4 6 6 2 2
     ;     5 6 6 1 1
           make a pixplot of this data - several plot options exist
           str = pixplot(ignore =';', xran=[0,12], yran =[0, 12])
           plotstr, str, /shade ; shade surface of the result
           plotsrt, str, /fill  ; filled contour plot
           plotstr, str, /fill, col=-1 , nl = 5; RGB type contour plot
    
           Make a pixplot with full grid with file 'junk.dat' and set background
             to 3
           junk = pixplot(ignore =';', xran=[0,12], /plot, 'junk.dat', $
                  ticklen = 1, /xgridstyle, /ygridstyle, default = 3)
    

    (See ../pfidl/pfidl_2d/pixplot.pro)


    PLOTBLK

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           PLOTBLK
    
     PURPOSE:
           Plot conputational grid or block boundaries as a solid model.
     CATEGORY:
           Input/Output
     CALLING SEQUENCE:
           PLOTBLK, A [, XRANGE = XRANGE] [, YRANGE = YRANGE] [, ZRANGE = zrange]
                   [, POLARPLOT = polarplot] [, BLOCK = BLOCK] [, COLOR = COLOR]
                   [, SHOWMODELS = showmodels] [, GETMODELS = getmodels]
                   [, CLEARMODELS = clearmodels] [, /AXIS_ORIENTATION] [, /VERBOSE]
                   [, NORMALIZE = normalize] [, OFFSET = offset]
                   [, ALENGTH = alength] [, AALENGTH = aalenght]
                   [, ACHARACTER = acharacter] 
     INPUTS:
           A        - PFIDL rectilinear grid or field structure
                      Type = 1 or 3
               or 
           A        - Variable to return the model if GET_MODELS is set
    
     KEYWORD PARAMETERS:
           XRANGE   - Two element vector defining the extent of the object in 
                      the X direction.  Any part of a block in the range will
                      be included.
           YRANGE   - Two element vector defining the extent of the object in 
                      the Y direction.  Any part of a block in the range will
                      be included.
           ZRANGE   - Two element vector defining the extent of the object in 
                      the Z direction.  Any part of a block in the range will
                      be included.
           POLARPLOT - If set, a polar plot will be generated.
           BLOCK    - The block of data to be plotted. Default is all blocks
           COLOR    - Indicates the color of the block, Color may be an array 
                      to sequence over colors.  If colors is an array, the
                      minimum value is 1 and the maximum is !d.table_size
                       The colors are: black(0), red(1), green(2), blue(3),
                       purple(4), orange(5), light blue(6), yellow(7) and white(8).
                      DEFAULT:  COLOR = 1+indgen(7)
         ShowModels - If present, all input is ignored and the current stored
                      models are listed.
          GetModels - If present, all input is ignored the indicated model is
                      returned in the first parameter.
        ClearModels - If present and greater than zero, all models are destroyed.
                      If negative, the indicated models are destroyed.
        AXIS_ORIENTATION - If set, X, Y and Z axes will be drawn.
                      DEFAULT:  Axis_Orientation = 1
        Verbose     - If set, data range and axis parameters will be provided.
        NORMALIZE   - If set, data will be normalized in the range [-1, 1]
                      If NORMALIZE is a 6 element vector, the data will be 
                      normalized in the ranges specified; that is, the first two
                      elements will be the first range for the first dimension, etc.
                      DEFAULT: NORMALIZE = 0
        The following are passed to ADD_AXIS
        OFFSET      - Axis offset from the data as a fraction of the data range.
                      DEFAULT: See ADD_AXIS
        ALENGTH     - Axis length as a fraction or the data range.
                      If ALENGTH is a 3 element vector, different values will be 
                      used for each vector.
                      DEFAULT: see ADD_AXIS
        AALENGTH    - Axis length in data coordinates
                      If AALENGTH is a 3 element vector, these valuse will be used.
                      If AALENGTH is a scalar, the actual values will be returned. 
                NOTE: AALENGTH is checked before ALENGTH
        ACHARACTER  - Character size
                      Default: See ADD_AXIS
    
     OUTPUTS:
           Designated blocks are plotted in XOBJVIEW
           NOTE:  When XOBJVIEW is closed the model remains.
                  USE:  PLOTBLK, /clearmodels
                  Models will be destroyed
     EXAMPLE:
           Generate a solid model from structure 3
            PLOTBLK, 3
    
           Clear all models.
            PLOTBLK, /clearmodels
    
           Get model 4 and view it
            PLOTBLK, a, GetModels=4  &  xobjview, a
    
     MODIFICATION HISTORY:
          Original version, L. P. Mix, November 24, 2003
    

    (See ../pfidl/pfidl_2d/plotblk.pro)


    PLOTCON

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           PLOTCON
    
     PURPOSE:
           Plot conductor geometry
     CATEGORY:
           Input/Output
     CALLING SEQUENCE:
           PLOTCON, A [, X] [, Y] [, ZVALUE] [, YRANGE = YRANGE] [, THICK = THICK]
               [, XRANGE = XRANGE] [, COLOR = COLOR] [, TITLE = TITLE] [, /ASPECT]
               [, XTITLE = XTITLE] [, YTITLE = YTITLE] [, /SOLID_MODEL] [, /AXIS_ADD]
               [, POLARPLOT = polarplot] [, SHOWDEFAULT = showdefault]
               [HEADER = header] [, SETDEFAULT = setdefault] [, UNSET = unset]
               [, OVERPLOT = OVERPLOT] [, IGNORE = ignore]  [, /ZEROTHICK] [, /PEC]
               [, FILL = fill] [, /NOPLOT] [, CLOSED_ONLY = closed_only]
               [, RESET_CONDUCTOR = reset_cond ] [, NODATA = nodata]
               [, QUIET = quiet] [, BLOCK = block] [, _EXTRA = extrastuff]
     INPUTS:
           A     IDL conductor  structure (type = 4)
           X     Abscissa values (1, 2, or 3 x, y, or z coordinates)
           Y     Ordinate values (1, 2, or 3 x, y, or z coordinates)
           ZVALUE Value of the coordinate in the third dimension. In the case of
                 two dimensional data, enter 0.
         Note: An error tolerance of the maximum range of the conductor data
               maxp = max(a.plane(1, *, *))
               minp = min(a.plane(0, *, *))
               err = 1.52588e-5*( max([maxp-minp, abs(maxp), abs(minp)]))
               used in determining whether a plane crosses a conductor.
         NOTE: If overplot is not zero, then x and y, zvalue will be determined
                 from he previous plot.
         NOTE: If the actual plot range exceeds the range specified by xrange or
               yrange and only one of these values has been specified, then
               then conductors may appear to begin in space.  That is, if only
               one plot range is specified (xrange or yrange) then the data is
               roughly windowed to that specification to determine the appropriate
               value for the other plot dimension.
    
     KEYWORD PARAMETERS:
           OVERPLOT - If not zero, indicates no new grid is to be drawn.
           THICK    - Line Thickness default is 2
           COLOR    - All lines will be drawn with a single color.
                       The colors are: black(0), red(1), green(2), blue(3),
                       purple(4), orange(5), light blue(6), yellow(7) and white(8).
           TITLE, XTITLE and YTITLE If grid is not zero, these will be used for
                     axis and the plot labels.  If these are not string arrays,
                     the title, xtitle and ytitle used for the plots will be used.
           SOLID_MODEL - If set, a solid model will be shown
                      Note: Structure must have the solod model information.
                            SEE Also:  SOLID
                      Note: See BLOCK and ADD_AXIS keywords
                      To return the model, use following:
                        model=1
                        plotstr, str, solid_model = model
           AXIS_ADD - Ignored unless SOLID_MODEL is set.  If set, an axis will be
                      added to the model.  If AXIS_ADD is a structure, it will be
                      passed to ADD_AXIS as an _EXTRA keyword.
           BLOCK    - If set, the solid model is displayed in a blocking widget
                      If undefined, then BLOCK defined by the following:
                           DEFSYSV, "!callable_idl", exists = BLOCK
           ASPECT   - If set, the ordinate and abscissa will have the same relative
                      scale
           POLARPLOT - If set, a polar plot will be generated.
                     For the SPARE[0] eq 1, no polar plot is generated
                     The coordinates for cylindrical and spherical data are as follows:
                       R     - Radius vector
                       PHI   - Angle between the radius vector projected on the X-Y
                               plane and the X axis
                       Z     - Axis normal to the X-Y plane
                       THETA - Angle between the Z axis and the Radius vector.
                     For the SPARE[0] eq 2, the cylindrical data will be converted
                       to cartesian and plotted; Coordinates=(R, Phi, Z)
                       X and Y must be 1 and 2 in any order, but they will be
                         set to 1 and 2 respectively.
                       The conversions are:
                         X = R * Cos(Phi)
                         Y = R * Sin(Phi)
                     For the SPARE[0] eq 3, the spherical data will be converted
                       to cartesian and plotted; Coordinates=(R, Theta, Phi)
                       The conversions to cartesian are:
                         X = R * Cos(Phi) * Sin(Theta)
                         Y = R * Sin(Phi) * Sin(Theta)
                         Z = R * Cos(Theta)
                       For (X, Y) equal to (1,3), Theta will be set and the abscissa
                         and ordinates will be X and Y, respectively.
                       For (X, Y) equal to (1,2), PHI will be set.  The plot will be
                         rotated to the slice value, and the abscissa and ordinates
                         will be X and Z, respectively.  Because of the rotation,
                         (PHI = 0) in the equation for X above.
    
                       ASPECT will be set unless it is explicitly unset.
                       Current version is for type 4 data only.
           X,YRANGE - Axis range(standard IDL meaning)
           HEADER    If specified a plot header, consisting of the current date
                     and the current file name, is displayed in the lower left
                     corner of the plot.  See the HEADER command to set default
                     HEADER parameters (character size, spacing, alignment).
                     DEFAULT is HEADER = 1
                     NOTE: For X-windows screen dumps, many will want to increase
                          the character size with the command:
                          HEADER, /set, charsize = 0.8
                          (Default is 0.6 of current size)
         SETDEFAULT- If present and not zero, then the following parameters will be
                     saved and used as the default values in all future calls to PLO
                     If a keyword is specified, it will always be used rather than
                     the saved values.
         UNSET     - If present and not zero, will set all save values of keywords
                     to their default values.
                     Normal default values are listed below.
                     Keyword     Default value
                     HEADER       1
                     XRANGE       0
                     YRANGE       0
                     COLOR        0 (!p.color)
                     THICK        2
    
         SHOWDEFAULT-Show the present default plot values.
         IGNORE    - If set and an overplot, ignore the previous values.
                     This includes X, Y, Z, POLARPLOT, etc.
         ZEROTHICK - If set, zero thickness planes will be plotted.
         PEC       - If set, zero thickness planes will be plotted.
                     Results are the same with either zerothick or PEC set.
         FILL      - If set, fill the conductor/dielectric.
                     If set, conductor will be stored in the TQPFIDL common block.
                     No attempt is made to close conductors.  POLYFILL will simply
                     connect the first and last points.
                     QSEDIT, /COND may be used to edit these values and
                     TQPLOTCON can be used to plot these conductors.
         NOPLOT    - Applies only to the fill keyword.  If set the conductors will
                     not be plotted but they will be stored in the TQPFIDL structures.
         CLOSED_ONLY - If set, fill only if all conductors are closed conductors
                     If any conductors are not closed, ignore fill.  All conductors
                     will be saved in the TQPFIDL common block.
         RESET_COND- If set, RESET will be set in the call to TQCOND.
                     Default:  RESET_COND =1
         LINE_FILL - If set, dielectric is filled with lines.  Ignored unless
                     FILL is set.
                     If LINE_FILL not equal to 1 then ORIENTATION = LINE_FILL.
                     POLYFILL is repeated N_Elements(ORIENTATION) Times.
                     IF LINE_FILL equal to 1 then ORIENTATION=[+45, -45]
                     Note: LINE_FILL is set if it is not zero or an array.
                     Default is solid fill or LINE_FILL =0.
         NODATA    - Plot only the axis.
         ORIENTATION - Ignored unless fill is set.
                     ORIENTATION is passed to POLYFILL if FILL is set.
                     This is same as LINE_FILL, but there is no default.
         QUIET     - If set, do not print warning messages.
         SPAWN     - If set, spawn XOBJVIEW to another process
           _EXTRA    additional parameters to the plot command. POSITION,
                     (X,Y)STYLE, (X,Y)TYPE have the standard IDL meaning.
     OUTPUTS:
           Designated datasets are plotted.
     EXAMPLE:
           Plot a TQ, 2D cylindricl structure A, with Z horizontal and R vertical.
             Use a limits: X = [0,0.064] and Y=  [0, 0.14]
             PLOTCON, A, 3, 1, xrange = [0,0.064],yrange = [0, 0.14]
    
           Overplot conductor geometry from structure 4
             PLOTSTR, 4, /over
    
           Plot a solid representation of the conductors in dataset 4 and 5 in the current
           PFF file with an axis
             READSTR, 23, [4,5], /solid
             PLOTSTR, 23, /solid, color = [1, 3], /axis
    
           Plot a filled conductor from structure 32 with Radius horizontal and Z vertical.
           at an angle of !pi/18
             PLOTSTR, 32, /reset, 1, 3, !pi/18, /fill
    
           Plot a filled conductor from structure 32 with Radius horizontal and Z vertical.
           at an angle of !pi/18 and add similar data from structure 33 and plot the data.
           NOTE:  PLOTSTR with /NODATA is used to make the grid.
             PLOTSTR, 32, /reset, 1, 3, !pi/18, /fill ; /RESET clears the TQPFIDL conductor
             PLOTSTR, 33,  1, 3, !pi/18, /fill ; these conductors are added to the TQPFIDL cond.
             QSEDIT, /cond ; if necessary for reasonable fill
             PLOTSTR, 33, 1, 3, !pi/18, /NODATA
             TQPLOTCON, /FILL
    
    
           Add the conductor in structure 33 to the above conductor 32 and plot the result.
           Before plotting check the conductors to make sure that the first and last points
           are satisfactory.  Make the first 3 conductors red and the next 2 green.
             PLOTSTR, 33, 1, 3, !pi/18, /fill
             TQEDIT, /cond
         QSEDIT, /cond
             ; generate a grid
             PLOTSTR, 33,  1, 3, !pi/18, /NODATA, title = 'Anode and Cathode'
             TQPLOTCON, /fill, color = [1, 1, 1, 2, 2]
       Note:  Last two commands may be replaced with the following:
             TQPLOTCON, /fill, color = [1, 1, 1, 2, 2], $
                 grid ={title:'Anode and Cathode', xtitle:'Radius', ytitle:'Z-Axis'}
    
     MODIFICATION HISTORY:
          Original version, L. P. Mix, March 5, 1993
          Modified: L. P. Mix, May 23, 2006
                    Allow for solid fill for conductors.
    

    (See ../pfidl/pfidl_2d/plotcon.pro)


    PLOTFE12

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           PLOTFE12
    
     PURPOSE:
           Converts a 3D finite element structure to a 2D rectilinear structure
           PLOTSTR is then called on that structure
    
     CATEGORY:
           Vizualization
    
     CALLING SEQUENCE:
           PLOTFE12, STR, KVALUE, VALUE [, WORK = work] [, _EXTRA = extrastuff]
            or
           PLOTFE12, STR, CENTER, ANGLE, /RZ [, WORK = work] [, _EXTRA = extrastuff]
    
     INPUTS:
           STR:    IDL type 12 structure or structure array number
           KVALUE: Indicates the coordinate which is fixed for the two
                   dimensional plots.
           VALUE:  The coordinate values for the fixed dimensions in
                   the two dimensional plots.
           (IF RZ is SET)
           CENTER: A two element vector or ZERO
                   If CENTER = 0, then CENTER = [0.0, 0.0]
                   This version requires the center in the computational volume
                   unless center = 0.  If center = 0 and the center is not in the 
                   computational volume, the slice will go from the point [0,0] to
                   [xmax, xmax*tan(angle)]
           ANGLE:  Angle between the X axis and the RZ plane.  ([-!pi/2, !pi/2])
                   Angle is in radians unless degrees is set
                   Angle is arbitrary, but it will be converted to quadrants 1 or 4.
    
     KEYWORD PARAMETERS:
    
           WORK:   Storage location for the 2 dimensional, rectilinear structure.
                   DEFAULT:  WORK = GET_MAXSTR() -1
           RZ:     If set, assume the data is cylindrical in Cartesian coordinates.
                   Plot R along the X axis and Z along the Y axis unless transplot is set.
           DEGREES:If set, the RZ angle is in degrees
           TRANSPLOT: If set, transpose the X and Y axes.
           _EXTRA:	Any valid keyword for PLOTFLD
    
     OUTPUTS:
           The output field is plotted.
           The rectilinear dataset is stored in WORK.
    
     PROCEDURE:
           The data is put interpolated on a rectilinear mesh using the plot parameters
           to determine resolution.  The IDL command QGRID3 is used.
    
     EXAMPLE:
           Plot structure 32 along a plane for y = 0.0
             PLOTSTR, 32, 2, 0.0
    
           Plot structure 32 along a plane for y = 0.1 and for xvalues from 0.0 to 0.001
             PLOTSTR, 32, 2, 0.0, xrange= [0.0, 0.001]
    
     MODIFICATION HISTORY:
     	Written by:	L. P. Mix, Jr., March 1, 2006
                           Added RZ keyword, lpm, May 1, 2007
    
    

    (See ../pfidl/pfidl_2d/plotfe12.pro)


    PLOTFLD

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           PLOTFLD
    
     PURPOSE:
           Plot field variable in a contour, surface, or shaded surface plot.
           This routine will also integrate field values with respect to the
             x and/or y values, and take lineouts of the values or integrated
             field values.
        Note: LOG PLOTS
           For log contours the two techniques may be used:
             1.  PLOTFLD, A, Multiply =0
                 (See the MULTIPLY keyword.)
             2.  LOGSTR, A, B
                 PLOTFLD, B
    
           WARNING:  PLOTSTR uses the _extra structure to pass variables. If
                     data is to be returned, PLOTFLD must be used.
           WARNING:  The maximum structure array will be used as a working
                     structure array and will contain the two dimensional data
                     used for the contour plot unless the keywork WORK provides
                     a valid working structure number.
                     The maximum structure array minus 1 is used by the POLARPLOT
                     keyword to store the converted structure.
    
     CATEGORY:
           Input/Output
     CALLING SEQUENCE:
           PLOTFLD, A [, FLD] [, KVALUE1] [, VALUE1] [, KVALUE2] [, VALUE2]
     (general         [, BLOCK = block] [, ASPECT = aspect] [, MULTIPLY = multiply]
                      [, ADD = add] [, KINTEGRATE = kintegrate] [HEADER = header]
                      [, SETDEFAULT = setdefault] [, UNSET = unset]
                      [, SHOWDEFAULT = showdefault] [, ALWAYS_PLOT = always_plot]
     plot parameters) [, INDEX = index] [, SMOOTH = smooth] [, POLARPLOT = polar]
                      [, FARRAY = farray] [, NFARRAY = nfarray]
                      [, XARRAY = xarray] [, YARRAY = yarray] [, ZTITLE = ztitle]
                      [, TITLE = title] [, XTITLE = xtitle] [, YTITLE = ytitle]
                      [, TRANSPLOT = transplot] [, /TRUNCATE] [, QUIET = quiet]
                      [, LEFT = left] [, RIGHT = right] [, /RBTHETA]
                      [, RESULT = result] [, WORK = work] [,NO_COPY = no_copy]
                      [, XRANGE = xrange] [, YRANGE = yrange] [, ZRANGE = zrange]
    
     (plot types)     [, CNTOUR = contour] [, C_RANGE = crange]
                      [, C_EXTRA = c_extra] [, IFLAG = iflag]
                      [, XSURFACE = xsurface] [, PIXPLOT = pixplot]
                      [, SHADESURF= shadesurf] [, SURFACE = surface]
                      [, S_EXTRA = S_extra]
                      [, CSHADESURF = cshadesurf] [, CS_EXTRA = cs_extra]
                      [, OSHADESURF = oshadesurf] [, /NEGATIVE] [, /FASTPLOT]
                      [, AXSURF= axsurf] [, AZSURF =azsurf]
     (contour param)  [, OVERPLOT = overplot] [IGNORE = ignore]
                      [, NLEVEL = nlevel] [, LEVELS = levels]
                      [, CLIP_VALUES = clip_values]
                      [, COUTPUT = Contour_Output_WDF_Arrays] [, COLOR = color]
                      [, XRANGE = xrange] [, YRANGE = yrange]
                      [, CONDUCTOR = conductor] [, GRID = grid]
     (Thermometer)    [, THERMOMETER = thermometer]
     (integrals)      [, XINTEG = xinteg] [, YINTEG = yinteg] [, START = start]
                      [, REVERSE = reverse]
     (lineouts)       [, XLINE = xline] [, HLINE = hline]
                      [, YLINE = yline] [, VLINE = vline] [, NPOINTS = npoints]
                      [, WIDTH = width] [,PLINE = pline] [, OUT = out]
                      [, CLINE = cline] [, CZERO = czero]
                      [, CABSCISSA = cabscissa] [, CMAXIMUM = cmaximum]
     (any stuff)      (any contour keywords -- see IDL manual-- examples include:
                      FILL, X(Y)TYPE, POSITION, X(Y)MARGIN, THICK, FOLLOW,
                      DOWNHILL, X(Y)TICKLEN, X(Y)STYLE,  C_ANNOTATION,
                      C_CHARSIZE, C_LINESTYLE, ....)
    
     INPUTS:
           A     IDL field structure (a.type = 1) or QS array number
           FLD   Field or attribute parameter to be plotted.
           Note: FLD may be positive or negative; for GET_ARRAY: SPACE = -(abs(FLD))
           Note: If FLD is an array, the square root of the sum of
                 the squares will be used.
                   If FLD =[1] the the absolute value is plotted.
                 If FLD is a single value array, ABS will be applied.
           Note: If FLD is a single value larger than the number of vector
                 components, then FLD = 1+indgen(nvect)
                    where nvect is the number of vector components
           Note: If A has only one attribute (such as an image or a charge density);
                 the this parameter can be omitted.
           KVALUE1, 2
                 If FLD is a two dimensional field then these values are ignored.
                 If FLD is a three or four dimensional field then these values
                   indicate the coordinates which are fixed for the two
                   dimensional plots.
                   For 3D plots, x and y are chosen according to:
                      x= (kvalue1 mod 3)+1 and y = (kvalue1+1) mod 3 + 1
                   For 4D plots, the lowest index is x than the other is y
           VALUE1, 2
                 If FLD is a two dimensional field then these values are ignored
                 If FLD is a three dimensional field then these values
                   indicate the coordinate values for the fixed dimensions in
                   the two dimensional plots. Linear interpolation is used
                   according to the value of VALUE1. If VALUE1 has two elements
                   the average value over the interval is used.
             Note: If INDEX keyword is set, the units are taken as array indices
                   which range from 1 to the maximum value.
             Note: If the two elements of VALUE1 span a block boundary, then only
                   the values in the block containing the midpoint will be used.
                   If the midpoint falls on a block boundary, then the result is
                   probably not what you want!!
     KEYWORD PARAMETERS:
    
     (General plot keyworks)
    
           BLOCK   - If the field is multi-block, BLOCK can be used to specify
                     one or more blocks to be plotted/integrated/...
           ASPECT  - If set, will attempt to scale axis based on xrange and yrange.
                     xstyle and ystyle are set
                     If this is a type 1 field structure and:
                       if ASPECT = "PIXELS" then:
                         The plot will have X and Y axis lenghts that are
                         proportional to the number of elements in the image
                         in the first block (thus this option should only be
                         used with single block data.)
                     else if ASPECT = "SQUARE" then the X and Y axes will be the
                         same length.
                     Only the first character will be checked; ie "P" or "S"
                     If ASPECT is set and the first character is not a "P" or "S",
                     then aspect will be assumed to be 1.
           POLARPLOT -  If set, a polar plot will be generated.
                     The type-8 structure procuced by the transform will be stored
                       in get_maxstr()-1.  Structure will have X and Y or X and Z in
                       the X1 and X2 dimensions.
                     The SPARE structure tag is used to determine the coordinate system
                     For the SPARE[0] eq 1, no polar plot is generated
                       (Already in Cartesian Coordinates)
                     For SPARE[0] equal to 2 - CYLINDRICAL coordinates
                     For SPARE[0] equal to 3 - SPHERICAL coordinates
    
                     The coordinates for cylindrical and spherical data are as follows:
                       R     - Radius vector
                       PHI   - Angle between the radius vector projected on the X-Y
                               plane and the X axis
                       Z     - Axis normal to the X-Y plane
                       THETA - Angle between the Z axis and the Radius vector.
                     For the SPARE[0] eq 2, the cylindrical data will be converted
                       to cartesian and plotted; Coordinates=(R, Phi, Z)
                       X and Y must be 1 and 2 in any order, but they will be
                         set to 1 and 2 respectively.
                       The conversions are:
                         X = R * Cos(Phi)
                         Y = R * Sin(Phi)
                     For the SPARE[0] eq 3, the spherical data will be converted
                       to cartesian and plotted; Coordinates=(R, Theta, Phi)
                 NOTE:  Constant THETA will not result in a planar plot at a fixed
                        value of Z but the projection of a conical plane at
                        constant theta projected on the X-Y plane.
                       The conversions to cartesian are:
                         X = R * Cos(Phi) * Sin(Theta)
                         Y = R * Sin(Phi) * Sin(Theta)
                         Z = R * Cos(Theta)
                       For (X, Y) equal to (1,3), X and Y will be calculated
                         according to the equations above and will be plotted.
                         X, Y equal to (1, 3) implies a slice in the theta dimension.
                       For (X, Y) equal to (1,2) (Slice in the PHI dimension)
                         X = R * SIN(X2)
                         Z = R * COS(X2)
                       TRANSPLOT will be set to zero.
                       ASPECT will be set unless it is explicitly unset.
                NOTE:
                      In the case of mapped mesh grids:
                        Assume the corners of the zone to be 1, 2, 3, 4 from lower
                        left to upper left, counter-clockwise around the cell.
                        The normal order for triangles is 1, 2, 3, and 1, 3, 4.
                        The command: junk = make_triangles(/toggle) will change the
                        triangles to 1, 2, 4 and 2, 3, 4
    
                      Example:
                          Replicate a field in theta and plot with conductors.
                          Assume zval = zval, conductors in 2 and field in 3
                            plotstr, /quiet, 3, 3, zval
                            image, 82, 4, refl=2
                            image, 2, 5,  refl=2
                            plotstr, 4, /polar, con= 5
           MULTIPLY- Multiply the field by a constant or a vector
                     If MULTIPLY(0) eq 0 then MULTIPLY implies a log plot
                           if MULTIPLY has 2 elements then
                              field_value = field_value*multiply(1)
                           FIELD_VALUE = ALOG10(FIELD_VALUE > MINVAL)
                           LEVEL = ALOG10(LEVEL)
                     Note: Enter MULTIPLY = [0, -1] to make a log plot of negative
                           data such as electron charge density.
                     Note: See also the routine: LOGSTR
                           LOGSTR will take the LOG of a structure
           ALWAYS_PLOT- If set, always plot the field.  If the range of the field
                     is zero, plot with level = value +[-1,+1]
           ADD     - Add a scalar to the field before plotting
                 Note: If F is the field then (multiply*F + add) will be plotted
    
                 NOTE: LOG PLOTS (MULTIPLY = 0)
                     If MULTIPLY eq 0, then ADD is used to determine a lower bound.
                        Default value: ADD = LOG_MIN ; (from LOGSTR)
                             Initial value (see LOGSTR ) LOG_MIN = 1e-4
                        The quantity plotted is ALOG10(FIELD_VALUE > MINVAL)
                               MIN = ADD
                               IF (MIN LT 0.0 or MIN GE 1) then
                                    MINVAL = ABS(MIN)
                               IF (MIN GT 0 AND  MIN LT 1) then
                                    MINVAL = MIN*MAX(field_value)
                 NOTE: LOG_MIN is used by LOGSTR.  The default value is the same
                       for both PLOTFLD and LOGSTR and may be set in LOGSTR
                 NOTE: LOG is always ALOG10 in PLOTFLD.
    
           KINTEGRATE - If present and not zero, integrate the slice rather than
                     average over the extent of value1(0) to value1(1).
                     The integral will be performed between value1(0) and value1(1)
                     If integrate = 1, a simple integral
                     If integrate = 2, a x dx integral
                     If integrate = 3, a x^2 dx integral
                     Limitations:
                         Data must have a single block
                         Two values of value 1 must exist
           HEADER    If specified a plot header, consisting of the current date
                     and the current file name, is displayed in the lower left
                     corner of the plot.  See the HEADER command to set default
                     HEADER parameters (character size, spacing, alignment).
                     DEFAULT is HEADER = 1
                     NOTE: For X-windows screen dumps, many will want to increase
                          the character size with the command:
                          HEADER, /set, charsize = 0.8
                          (Default is 0.6 of current size)
         SETDEFAULT- If present and not zero, then the following parameters will be
                     saved and used as the default values in all future calls to
                     PLOTFLD
                     If a keyword is specified, it will always be used rather than
                     the saved values.
         UNSET     - If present and not zero, will set all save values of keywords
                     to their default values.
                     Normal default values are listed below.
                     Keyword     Default value
                     HEADER       1
                     COLOR        FLDCOLOR (-1 typically)
                     XRANGE       0
                     YRANGE       0
                     NLEVEL      20
                     LEVELS       0
                     INDEX        0
                     THERMOMETER  0
                     ASPECT       0
                     TRUNCATE     0
                     CNTOUR       1
                     ALWAYS_PLOT  0
                     C_COLOR      [9, !d.table_size-2]
               NOTE: The following is set in LOGSTR
                     LOG_DEFAULT  1.0e-4
    
         SHOWDEFAULT-Show the present default plot values.
           INDEX   - If present and not zero, then the units of VALUEi will be
                     taken as indices of of the field array.  Valid values are
                     1 to the maximum number of values in KVALUEi.
                     Care should be exercised with multiple block data.
           SMOOTH  - If present and not zero, the two dimensional field will be
                     smoothed using a boxcar filter.  The number of cells will
                     be the lowest odd number greater than or equal to the
                     maximum of [3, SMOOTH]
                     If SMOOTH is less than zero then the Absolute value of
                     SMOOTH will be used as a median filter with a width equal to
                     the maximum of [3, abs(SMOOTH)]
           FARRAY, NFARRAY - For single block data FARRAY is the field quantity
                     being plotted and NFARRAY is ignored.
                     For multiple block data, a uniform grid is generated with
                     NFARRAY by NFARRAY elements. The field quantity is
                     interpolated to this grid.
               Note: If nfarray is undefined, then farray will not be returned
                     unless a plot is made.  If CN=2 then farray has the dimension
                     of the plot area in pixels.  If CN = 1 then farray will be
                     a scalar 0 for single block data.  The work array always
                     contains the actual data plotted.
               Note: All plots, except contour plots, plot the array, FARRAY.
                     For multiple block data:
                     CNTOUR = 1 (/CNTOUR)
                     For standard contour plots, the default value of NFARRAY
                     is 128 if NFARRAY is equal to 1, or abs(NFARRAY) > 16.
                     (That is "/nf" would result in a value NFARRAY = 128)
                     If NFARRAY is undefined, then NFARRAY = 0 unless SURFACE,
                     SHADESURF, or XSURFACE is set.
    
                     CNTOUR = 2 (or 3)
                     For contour plots using a continuous color scale, FARRAY
                     is the size of the plot area in PIXELS without scalable pixels.
                     With scalable pixels the number of elements will be the actual
                     array if it is larger than (750 x 600). If the array is smaller
                     than this then the array will be resampled to a density of
                     about 50 pixels /cm.
    
           XARRAY, YARRAY - Abscissa and ordinate values for the array, FARRAY
           TITLE, XTITLE and YTITLE - If these are character strings, they
                     will be used as the plot title and the axis labels.
                     If they are not character strings or are undefined (i.e.,
                     delvar, title, xtitle, ytitle) then they will be returned
                     with the values actually used for the plots.  The default
                     TITLE is the dataset comment. The title will be truncated
                     at a double simicolon (;;) or at the following string:
                     ';DATETIME='. The default axis labels are the PFF axis
                     labels read with the data.
           ZTITLE    If set, will be used for cshade_surf.
           TRUNCATE -  If set to zero, the full dataset comment will be used as
                       a title. Default is to not limit the title to the characters
                       before the first ' - ' in the comment. (TRUNCATE =0)
                       If truncate is set only caracters before a ' - ' will
                       be used and only the dataset comment will be used.
           TRANSPLOT-If present and not zero, interchange ordinates and abscissa
                     SETDEFAULT can be used to set a default value
           QUIET   - If present and not zero,level information will not be printed.
                     If quiet has a value of 1 (/QUIET or QUIET =1), NO plots
                     will be make.  If QUIET is not zero and not 1, then plots
                     will be made, but no output to the terminal.
                     Default: QUIET = 0
           LEFT     Indicates a new plot using the left axis.
                    A single axis will be drawn on the left side of the grid
                    For this plot XMARGIN will be set to
                       XMARGIN = [!X.margin(0), !X.margin(0)]
                    and YSTYLE = 8.
                    NOTE: If LEFT is set, OVERPLOT is set to 0.
                    Note: Enter a value of ystyle of 8 plus the desired value
                          if any other ystyle values are desired.
                    Example:
                       Make a series of lineouts and overplot them on the contour
                       plot. Average the second spatial component between [0,1 ]
                       and take lineouts at .13, .14, .15.
                     plotstr, 1, 1, 2, [0,1], xl = [0.13,.14,.15], /pl, /left
                     plo, 1, 3, /over, /right, /ns, /color, thick = 3
          RIGHT     Indicates a OVERPLOT making and using the right axis.
                    If RIGHT is present and not zero, then:
                      A single axis will be drawn on the right side of the existing
                        grid
                      The field data will be overplotted on the existing grid.
                    Before using this command, a plot should be created using
                      the keyword: /LEFT
                    NOTE: If RIGHT is set then OVERPLOT and IGNORE are set to 1.
                    NOTE: After this command all memory of the original y-axis
                          scaling is lost
           RBTHETA - If set and:
                       1. structure has 3 field components
                       2. Sturcture is type 1
                       3. fld is 2
                     then use chastr, B_structure, s2v = 1, /space
                     to convert Btheta to R*Btheta.
                     Ignored otherwise.
           RESULT  - Structure array number to be used to store farray,
                     xarray, yarray, title, xtitle, ytitle.
                     This array contains a single block structure.
                     Note: If No_Copy is set then result will not be saved.
                           If result is undefined, then farray will not be saved.
           WORK    - Structure array number to be used as a working array.
                     Default is maxstructure. This will have the same number of
                     blocks
                     Note: If NO_COPY is set then work will not be saved.
           NO_COPY  - If this keyword is set then the plotted data will not
                     be saved in WORK. Use for very large arrays.
                     If the number of data elements is greater than 2,000,000
                       and N0_COPY is not set then NO_COPY =1 for type 1 data
    
     (Plot types)
    
           NOTE:   - Default plot type is contour plot
                     If no other plot types are selected, a contour plot will
                     be drawn by default.
                     If fill is set, a pixmap will be generated.
                     If the field contains more than 40000 elements, a pixmap will
                     be generated.
           CNTOUR  - Set the default contour type. Each bit indicates a different
                     type of plot. Multiple plots can be specified.  If no other
                     plots are specified, then CNTOUR will be set according to:
                     If PIXPLOT is set, then CNTOUR = (2 or CNTOUR)
                     If CNTOUR is undefined and N_elements(C_EXTRA) lt 3 then
                        CNTOUR = CNTOUR_SAVE
                     If CNTOUR is undefined and N_elements(C_EXTRA) ge 3 then
                        CNTOUR = 2 or CNTOUR_SAVE
                     Each bit of CNTOUR specifies a plot.
                     CNTOUR = 1 or 3
                     Standard contour plot.
                    (If value is 3, first a scaled color plot then the contours.)
    
                     CNTOUR = 2 (or 3)
                     Continuous scaled color plot (Image type plot).
                     Note:  All colors will be used unless CRANGE is set.
                     If CNTOUR < 0 CNTOUR = abs (CNTOUR) and default field is zero.
               Note: CNTOUR = 2 will cause the entire plot area to be replaced.
                     Any data on the screen will be overwritten.
                     For CNTOUR = 2 background color will be at 1% of the minimum.
               Note: Do not use CNTOUR = 2 with RIGHT or OVERPLOT set.
               Note: /NEGATIVE will make the tick marks in the background color
           C_RANGE:  Two element vector specifying the range of the color table to
                     use for CNTOUR = 1,2.
                     First number is the lower value, and second is the upper
                     value expressed as a fraction of full scale.
                     If C_RANGE LE 1:
                       NCOL = !d.table_size -11
                       (For true color devices, !d.table_size = 256)
                     If C_RANGE GT 1:
                     Elements of the color table can be specified.
                     The smallest number should be greater than 8 and the larger
                     number should be less than (!d.table_size-1)
                     If not they are not in this this range, they will be changed.
                     DEFAULT: C_RANGE=[0,1] = [9, !d.table_size-2]
           NEGATIVE: If set and either FILL is set or CNTOUR =2, 3 then the
                     grid tick marks are in the background color.
           FAST_PLOT: If set and single block data, then data reduced to 100 x 100
           C_EXTRA - Specifies solid fill regions for CNTOUR = 2 plots.
                     C_EXTRA must have a minimum of 3xn elements (n >= 1).
                     If C_EXTRA is defined with 3 or more elements, then
                     If CNTOUR is undefined then CNTOUR = (2 OR CNTOUR_SAVE).
                     If CNTOUR is defined to be 1 then C_EXTRA is ignored
                     C_EXTRA must have 3 or more elements. Format is of the form:
                       C_extra =[color1, min1, max1, color2, min2, max2, ...]
                     Where color1 exists between min1 and max1, etc.
    
               Note: Normal PLOTFLD commmand can be used to make filled regions
                        without an image type plot.
                     plotfld, str, color=[color1, -1, color2, -1], cn=1, $
                          level =[min1, max1,  min2, max2], /fill, nlev = 4
                     where the levels are in in assending order.  If max1 equals
                     min2 then the first -1 color can be deleted.
                     If normal contours are are desired, they must be plotted
                       using the overplot keyword.
                     for example: plotfld, str, /over, cn=1
           IFLAG   - If set to 1, the interpolation for CNTOUR =2 will be done
                     with rounding to the nearest X value.
                     If set to 2, the interpolation for CNTOUR =2 will be done
                     with rounding to the nearest Y value.
                     If set to 3, the interpolation for CNTOUR =2 will be done
                     with rounding to the nearest X value and the nearest Y value.
                     IFLAG = 3 is similar to PIXPLOT
                     If A surface plot only lines of constant X or Y (1, 2) will
                        be drawn depending on the value of iflag.
           SURFACE - If present and not zero, a surface plot of the field is
                     generated using the interpolated array, FARRAY.
             Note: The 3D transform is saved.
                     If IFLAG is set, individual curves in x vs z or y vs z will be
                       drawn.
           S_EXTRA - Extra parameters for surface plots
                     Note: CS_EXTRA can be used for adding keywords for the Surface
                           plots.
                     This may provide keywords for the surfact plot or add colored
                       overlays to a surface plot.
                     This is a structure.
                     The following are valid tags:
                     Spectrum: If set, colors are ignored. (see RAINBOW)
                     Values: X or Y values for highlighting
                             If IFLAG is not set, these are assumed to be Y values
                                ie IFLAG = 2
                     Colors: Colors for these curves.
                             Valid values are [0, !d.table_size-1]
              Note:  Only the first character is checked.
    
           SHADESURF-If present and not zero, a shaded surface plot of the
                     field is generated using the interpolated array, FARRAY.
             Note: The 3D transform is saved.
           OSHADESURF - If set, an object graphics shade surf is provided.
           CSHADESURF-If present and not zero, a shaded surface plot of the
                     field is generated using the interpolated array, FARRAY.
                     The plot will use shades to color code the amplitude and
                     overlay a surface plot.
                     If CSHADESURF is less than 0, then surface plot is deleted.
             Note: The 3D transform is saved.
           CS_EXTRA- Structure with Keywords and values which can be used with
                     SHADE_SURF and SURFACE.
                     Example to set charsize to 3 use: CS_EXTRA={charsize:3}
           XSURFACE- If present and not zero, an xsurface plot of the field is
                     generated which allows rotation and resizing of the data
                     using the interpolated array, FARRAY.
           PIXPLOT - If present and not zero, a pixplot is generated.
                     The coordinates are assumed to
                       be on the boundary and boundary cells are only 1/2 (1/4 for
                       the corners) of the size of interior cells.
                     If dataset type is 8 (Finite element data) then negative pixplot
                       is the symbol size
                     Color is determined by the following:
                        keyword color = -1 (DEFAULT)
                        color = (Amplitude-FMIN)/(FMAX-FMIN)*(!d.table_size-11)+9
                        keyword color = -2
                        color = ((round(abs(amplitude))-1) mod 7)+1
                     where FMIN and FMAX are the minimum and maximum values.
                     If PIXPLOT is set then the minimum and maximum level values
                       are set to fmin, fmax.
                     Example:
                       Make a pixplot for data in the range 422784 to 578304.
                         and add a thermometer.
                       plotfld, 4, /pix, ther= {ystyle:1, yrange: [4, 6]}, m = 1e-5
           AXSURF  - X rotation for SURFACE and SHADESURF
           AZSURF  - Z rtoation for SURFACE and SHADESURF
    
     (Contour plot keywords)
    
           COUTPUT - If set, this specifies the initial WDF array for the
                     x-y Pairs which specify the output contours.
                     Successive wdf arrays are used.
                     Output is from the CNTOUR=2 data.
                     If COUTPUT is less than 0 then all data will be saved.
                     If COUTPUT is greater than 0, then only lines with more than
                       3 points are saved.
                     If min(coutput) lt 1 then coutput = abs(coutput) > 1
                     Output ceases when the maximum WDF array is saved.
    
                     CNTOUR is set to 3.
                     If quiet is set, no plot will be generated.
                     EXAMPLE;
                       Store the contour from structure 7 for lev = [10, 1000]
                       in wdf array 40,41
                          plotstr, 7, cout=40, lev = [10, 1000], nlev=2
           OVERPLOT- If present and not zero, then the existing grid is to be used.
                     IF CN=2, then:
                      overplot > 0: Regions of the current plot with background
                                    values will use the previous values of the plot.
                      overplot < 0: Regions of the previous plot with background
                                    values will use the new values of the plot.
                     This option is ignored if any type of surface plots are made.
                     NOTE:  IF X windows are used, then the data will be read
                            from the screen for the above options.
                            Otherwise only the last CN=2 bitmap will be used.
                     With this option set, previous values of KVALUE1 and VALUE1
                     are used by default as well as the choice of abscissa and
                     ordinate coordinates. This option assumes that the previous
                     plot was from a PLOTFLD, PLOTGRD, PLOTCON, or PLOTPAR
                     command and attempts use the same parameters for the current
                     plot.  To use OVERPLOT with an arbitrary grid, set the
                     IGNORE keyword.  OVERPLOT is set to 1 if RIGHT is set.
           IGNORE  - This keyword is ignored unless OVERPLOT is set.  If OVERPLOT
                     is set and IGNORE is set, then all previous plot information
                     is ignored.  IGNORE is set to 1 if RIGHT is set.
           NLEVEL  - Number of contour plot levels.
                     Default = 20.
           LEVELS  - Array of values for the plot contours. If NLEVEL is specified,
                     then the values in levels are ignored unless there are exactly
                     NLEVEL values.
                     If not then the values of levels are:
                       LEVELS = minL + (findgen(NLEVEL)+0.5)*(maxL -minL)/(NLEVEL)
                     where minL and maxL are the minimum and maximum values of
                       LEVELS unless it has a single value then they are the maximum
                       and minimum values of the data.
                     The actual contour levels will be returned in LEVELS.
                     For image (CNTOUR=2) plots, the levels go from from min to max
                     of LEVELS.
               NOTE: If PLOTSTR is used, the levels will NOT be returned because
                     the EXTRA keyword is used to pass this value in a structure.
          CLIP_VALUES If set, set any levels below the minimum to the background.
                     If CLIP_VALUES = -1, then clip all values outside the
                       range of LEVELS.
                     Default = 1 ===>> clip only the values below the minimum.
          C_LABELS - Array of integers of value 0 or 1 to indicate if contour lines
                     are to be labeled. Default is no labels on the contour lines
                     If "/FOLLOW" is used as a keyword C_label is set to the array
                     [1,0,1,0,1, ...] and every other  line is labeled.
                     If C_LABEL= make_array(30, /fix, val= 1), then every contour
                     is labeled.
           COLOR   - Array of colors for the contour lines.
                     If color is an array, then
                       negative values will be set to !p.background
                     If color is not an array, then
                       If color = -1 then colors will go from c_range[0] to
                         c_range[1] uniformly spaced using the existing color table
                       If color = -2 then the 7 primary colors will be used to make
                         a color map.  With 20 levels we will have 3 red, 3 green,
                         3 blue, 3 purple, 3 orange, 3 light blue, and 2 yellow.
                       If color = -3 the 7 standard colors will be cycled.
                       If color is positive, that color will be used for all
                         contours, [1,7] are the primary colors, 9 to !d.table_size
                         depend on the color map.
                       Color = 0 is the default plot color ie white or black
                     Default is set by SETDEFAULT  or QSINIT
                     EXCEPTION: If CNTOUR and 3 = 3 then the Default color is:
                     c_color=[make_array(nlev/2, val = c_range[1]), $
                              make_array(nlev - nlev/2, val = c_range[0])]
                     The colors are: red(1), green(2), blue(3),
                     purple(4), orange(5), light blue(6), yellow(7).
           XRANGE, YRANGE - Two element arrays indicating the desired axis scaling.
                     If they are scalar or undefined, the actual data range will
                     be returned in these variables.
           ZRANGE  - Range of the field
           CONDUCTOR-Specifies a conductor structure or structure array number
                     specifying a conductor structure.  If valid, the
                     conductors will be overplotted.  Colors and thicknesses
                     can be set with SETDEFAULT.
           GRID    - Specifies a grid structure or a structure array number.
                     If valid, the grid will be overplotted.  Color and
                     thickness can be set with SETDEFAULT.
    
     (THERMOMETER keywords - used with contour plots)
           THERMOMETER- If keyword is set a thermometer will be generated with
                     the contour plot.  If thermometer eq -1, then the xmargin
                     will be set to [10, 10] but no thermometer will be drawn.
               Note: If THERMOMETER is a structure, then TPARAM is
                     set equal to THERMOMETER.  TPARAM is passed to the
                     THERMOMETER routine.
                     Default IDL margins are [10, 3] for x and [4, 2] for y
                     If TPARAM does not have a Tag Name beginning with 'CU'
                     then:
                     If no tag names begin with 'H' xmargin will be set to
                       [!x.margin(0), 10]
                       otherwise ymargin will be set to [8, !y.margin(1)]
               Note: xmargin or ymargin passed to plotfld will override
                           these settings.
    
     (INTEGRAL keywords)
           XINTEG  - Integrate the field variable with respect to the abscissa
                     value (x) according to the following values:
                     If XINTEG = 0, do nothing.
                     If XINTEG = 1, integrate f(x, y) dx
                     If XINTEG = 2, integrate f(x, y) x dx
                     If XINTEG = 3, integrate f(x, y) x^2 dx
                       dx is the spacing between abscissa values.
                     The initial value of the integral is set to 0.0 or
                       to the value in the WDF array specified by START.
               Note: If the resultant plot has contour lines passing through
                     conductors, TQCLEAN can be used to improve the appearance
                     of the plot.
               Note: If two blocks terminate on a third, then the initial value of
                     of the integral at the block boundary is linearly interpolated
                     between the two incomming blocks.
           YINTEG  - Integrate the field variable with respect to ordinate
                     value (y) according to the following values:
                     If YINTEG = 0 or if XINTEG = [1,2,3], do nothing.
                     If YINTEG = 1, integrate f(x, y) dy
                     If YINTEG = 2, integrate f(x, y) y dy
                     If YINTEG = 3, integrate f(x, y) y^2 dy
                       dy is the spacing between ordinate values.
                     The initial value of the integral is set to 0.0 or
                       to the value in the WDF array specified by START.
               Note: If XINTEG ne 0 then YINTEG is ignored.
               Note: If two blocks terminate on a third, then the initial value of
                     of the integral at the block boundary is linearly interpolated
                     between the two incomming blocks.
           START     If present this is interpreted as initial values at the lower
                     limit of integration. Start is an integer indicating a WDF
                     array.  Values are between 1 and maxwdfarray.  Any blocks
                     with coordinates in the domain of START will be initialized
                     unless they are connected directly to another block.  Values
                     at one point on a boundary are propagated along the entire
                     boundary and linearly interpolated between adjacent values.
           REVERSE   If present and not zero, the limits of integration are reversed
    
     (LINEOUT keywords - Values of the LINEOUT coordinates are determined
           in the following sequence.) For lineouts parallel to an axis
    
           1.  Two elements in width - These values taken as the max/min value
           2.  NPOINTS >0, NPOINTS equally spaced lineouts in specified
               direction(s), spacing is between the specified range --
               use xrange and yrange to limit the values of the lineouts.
               If NPOINTS eq N_ELEMENTS(XLINE) or NPOINTS eq N_ELEMENTS(YLINE)
                  those values are used for the X/Y Lineout.
           3.  XLINE, YLINE is an array of values for the lineout
          Note: To take a single lineout at one location width must be specified
                with two values (which may be equal) and /xline or /yline
                specified to indicate the direction of the lineout.
             OR NPOINTS = N_ELEMENTS (X/YLINE) then NPOINTS lineout will be taken
                at the appropriate y or x location specified by XLINE or YLINE with
                a width specified by WIDTH
          Note: If a single value is present, it will be adjusted to the closest
                boundary if the point lies outside the domain of the data.
                If multiple values are present, only valid points are used.
           Note: If the width of a lineout spans a block boundary, only values
                 in the block containing the midpoint of the lineout will be used.
    
           XLINE, HLINE - If present and not zero, a lineout is taken in the X or
                     horizontal directon.  If HLINE is present then:
                       XLINE = HLINE
                     and any xline value is ignored.  A WDF array of field value
                     vs the abscissa is generated at designated ordinate values.
                     If np is omitted, lineouts are taken at valid values of XLINE.
           YLINE, VLINE - If present and not zero, a lineout is taken in the Y or
                     vertical directon.  If VLINE is present then:
                       YLINE = VLINE
                     and any yline value is ignored.  A WDF array of field value
                     vs the ordinate is generated at designated abscissa values.
                     If np is omitted, lineouts are taken at valid values of YLINE.
           NPOINTS - Indicates number of lineouts in the X and/or Y direction.
                     NOTE: If npoints = n_elements(XLINE) or N_elements(Yline),
                           xline and/or yline are assumed to equal the desired value
                           of the lineout.
                           If x/yline is less than the minimum value then a lineout
                             is taken at the minimum value.
                           If x/yline is more than the maximum value then a lineout
                             is taken at the maximum value.
           WIDTH   - If a single value, then it is taken as the width of the
                     lineout.  Default value is 0.
                     If two values are present, they are taken as the mimimum and
                     maximum values for obtaining the lineout.
                     In all cases, the average value between the limits or in the
                     Width about the designated point is used for the lineout.
           PLINE   - If present and not zero, plot a dashed line at the position
                     of the lineouts
           OUT     - Value of the first WDF array for storing lineouts or an array
                     of values for the lineouts.  Default is OUT=1
                     (See W2I in the PFIDL help.)
       Lineouts along conductors
           CLINE   - If present and not zero, a lineout along a conductor will be
                     taken.  The value of cline corresponds to the conductor
                     number in QSEDIT.  If CLINE is negative lineouts will be taken
                     of all conductors.  The WDF array generated will be stored in
                     WDF array number, out, or the next WDF array following the
                     X and Y lineouts. All waveforms are stored as XY data.
                     Note: To obtain conductor geometries the TQ suite must be used.
                           TQEDIT/QSEDIT can be used with the other routines to
                           generate an arbitrary line.
                           To use the actual geometry the following can be used.
                         Read geometry - assume conductors in datasets 3, 4, 5, 6
                            READSTR, 1, 3, 4
                         Put the geometry into the TQ suite in Z-R, Z-X orientation
                         and cut at y or theta = 0:
                            TQREADCON, 1, 3, 1, 0
                         Edit the geometry if necessary:
                            QSEDIT, /cond
                         Take the lineout along all conductors
                            PLOTSTR, 2, 1, 2, 0, cline = -1, con = 2
                   Technique:  If dx and dy are less than 2^(-14) to a field point
                               then that point is used. If not then the four closest
                               field values are used to calculate a weighted
                               average.  Values less than 2^(-14)*range are not
                               used unless CZERO is set. Weight is (dx*dy)^(-1)
           CABSCISSA - Specifies the independent variable for the lineout.
                       If CABSCISSA is negative then CABSCISSA = abs(CABSCISSA)
                     1 - X-value, 2 - Y-value, 3 - Length=sqrt(x^2+y^2)
                     Default = 1
           CMAXIMUM - Maximum point spacing. Generally only nodes in QSEDIT will be
                      used but additional points will be inserted if the spacing
                      exceeds cmaximum.
           CZERO    - In general all values less than 6.10352e-5* (range of field)
                      are ignored.  If CABSCISSA is negative then CZERO is set.
                      IF CZERO is set, then all values will be used.
                NOTE: CZERO is not a normal keyword but is set if CLINE eq -1
    
     OUTPUTS:
           Designated datasets are plotted and WDF arrays generated for lineouts.
     Contour plots:
      Maximum number of levels is 30.
      CNTOUR will be used to determine plot type.
    
       CNTOUR and 1 = 1 (Current Default)
       Default is 20 levels, maximum is 30 levels.
       LEVELS, if specified, will be used to set levels.
       (If NLEVELS is specified and not equal to the number of values in LEVELS
        then there will be NLEVELS levels between the max and min of LEVELS.)
    
       CNTOUR and 2 = 2
       Image will be a continuous gradient of color table from 9 to !d.table_size-2
       with values corresponding to the 1% and 99% of the range of the data.
       If LEVELS has two or more values then color 9 is the minimum value and
       color !d.table_size-2 will be set to the maximum value.
    
       For example:
     To put red hatching between .3 and .4 on a standard contour plot with levels
     at intervals of 0.1 for structure 3 use with a thermometer:
        plotstr,3,level=[.3,.4],nl=2,c_orientation=45,color=[1, -1],ther=-1,$
           /fill, c_thick = 2
        plotstr,3,levels = findgen(20)/10 , /over, /th
    
     Similarly for solid red fill use:
        plotstr,3, level=[.3, .4], /fill, color=[1, -1], nl = 2, TH=-1
        plotstr,3,levels = findgen(20)/10 , /over, /th
    
     To obtain a continuous gradient plot with red between .3 and .4  and
     green between .7 and .8 use:
    
       plotstr, 3,c_extra=[1, .3, .4, 2, .7, .8]
    
    
     EXAMPLE:
           Contour plot of the charge density, in structure F, from a 2-D calc.
             plotfld, f
           (to add a thermometer with a plot with title Voltage, and tick values of
                [0, 5, 10]
             plotfld, f, /thermom, tparam={title:'Voltage', tickvalue:[0,5,10]}
    
           Contour plot of the charge density, in structure F, from a 3-D
           calculation taking a slice for the second dimension equal to 0.0
             plotfld, f,1, 2, 0.0
      (or)   plotfld, f,   2, 0.0 (since only one attribute, 1 can be omitted)
    
           Contour plot of the CR-39 track distribution with the third dimension
           the track size index in structure, C. Average tracks in bins 2 through
           10.
            plotfld, c,    3, [2, 10], /index
      (or)  plotfld, c, 1, 3, [2, 10], /index
      Note: Add ", m = 9" to plot the total number of tracks (since average is over
            9 bins (2 to 10)
    
           Contour plot of the magnitude of the vectors in structure START from
           TWOQUICK simulation (ie. Only two spatial dimensions).
             plotfld, start, [1,2,3]
    
           Contour plot of two dimensional structure array 1 of charge density
           (ie only 1 attribute)
             plotfld, 1
    
           Plot a slice of an image file, and take lineouts in the x and y
           directions through a feature in the contour plot.  Assume the image
           is in structure array 4 and an average over k components 3 to 10 is
           desired. The lineout width is 0.01 and lines indicating lineouts are
           to be plotted.
           Note: Plotstr and plotfld may be used interchangably.
             plotstr, 4, 3, [3, 10]
             cur, x, y (place cursor over the center of the feature)
             plotstr, 4, 3, [3, 10], np=1, xline = y, yline = x, wid = 0.01, /pl
    
           Contour plot of vector 1 of field structure a. Use a value of 0.4
             for spatial dimension 2 and take lineouts at 10 locations in the
             first and third dimensions and store the lineouts in WDF arrays 11
             to 30.  Sequence colors over the contour lines.
             plotfld, a, 1, 2, 0.4, /xl, /yl, npoint = 10, out = 11, color=-1
    
           Plot from structure a, vector 3 in a contour plot after smoothing.
           Set the value of the first dimension to 0.05
           Sequence linestyles over the contours.  Take a lineout between
           values of the second dimension of 1 and 2 and store in WDF array 1.
           (Note: The FOLLOW keyword should be used with multiple line types.)
           plotfld, a, 3,1,0.05,/smo,c_line = findgen(6),/follow, /yl, wid=[1,2]
     or plotfld, a, 3,1,0.05,/smo,c_line = findgen(6),/follow, yl=1.5, wid=1, np =1
    
           Make a shaded surface plot from structure END, vector 1, after
           smoothing, and generate verticle lineouts at intervals of 0.1
           between 1 and 2.5.  Assume structure END has two spatial components.
           plotfld, end,1, yline= findgen(16)*0.1+1, /smo, /sha
    
     MODIFICATION HISTORY:
          Original version, L. P. Mix, March 15, 1993
    

    (See ../pfidl/pfidl_2d/plotfld.pro)


    PLOTGRD

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           PLOTGRD
    
     PURPOSE:
           Plot conputational grids or block boundaries.
     CATEGORY:
           Input/Output
     CALLING SEQUENCE:
           PLOTGRD, A [, X] [, Y] [,ZVALUE] [, XRANGE = XRANGE] [, YRANGE = YRANGE]
                  [, INDEX = index] [, POLARPLOT = polarplot] [, QUIET = quiet]
                [, THICK = THICK] [, COLOR = COLOR] [, TITLE = TITLE]
                [, XTITLE = XTITLE] [, YTITLE = YTITLE] [, SKIP= SKIP]
                [, LINESTYLE = LINESTYLE] [, BLOCK = BLOCK] [, IGNORE = ignore]
                [, XARRAY = XARRAY] [, YARRAY = YARRAY] [, OVERPLOT = overplot]
                [, CONDUCTOR = CONDUCTOR] [, PRINTFILE = PRINTFILE] [, /ASPECT]
                [, HEADER = header] [, SETDEFAULT = setdefault] [, UNSET = unset]
                [, FRAME = frame] [, SHOWDEFAULT = showdefault] 
                [, LABEL_BLOCK = labelblock] [, LCHARSIZE = LCHARSIZE]
                [, FILL = fill] [, NO_GRID = no_grid] [, FColor = FColor]
                [, LCOLOR = lcolor] [, LEXTRA = lextra] [, _EXTRA = extrastuff]
     INPUTS:
           A     IDL grid structure (type = 3 or 10 or 11)
           X     Abscissa value (1, 2, or 3 depending on desired spatial array)
           Y     Ordinate value (1, 2, or 3 depending on desired spatial array)
           ZVALUE  For three dimensional data, value of plane in the third 
                   dimension. Default is them mean of the minimum and maximum.
                   If only 1 parameter other than A is provided, it is assumed to
                   be ZVALUE
           INDEX   If set, zvalue refers to a zvalue index (1, 2, 3, 4, 5, ...)
           Note: In the case of an overplot, the x and y values will be determined
                 from the previous plot.
     KEYWORD PARAMETERS:
           OVERPLOT - If not zero, indicates no new grid is to be drawn.
           THICK    - Indicates line thickness for the grid default is 0.6
           ASPECT   - If set, the ordinate and abscissa will have the same 
                      relative scale
           POLARPLOT - If set, a polar plot will be generated.
                     For the SPARE[0] eq 1, no polar plot is generated
                     The coordinates for cylindrical and spherical data are as follows:
                       R     - Radius vector
                       PHI   - Angle between the radius vector projected on the X-Y 
                               plane and the X axis
                       Z     - Axis normal to the X-Y plane
                       THETA - Angle between the Z axis and the Radius vector.
                     For the SPARE[0] eq 2, the cylindrical data will be converted
                       to cartesian and plotted; Coordinates=(R, Phi, Z)
                       X and Y must be 1 and 2 in any order, but they will be
                         set to 1 and 2 respectively.
                       The conversions are:
                         X = R * Cos(Phi)
                         Y = R * Sin(Phi)
                     For the SPARE[0] eq 3, the spherical data will be converted
                       to cartesian and plotted; Coordinates=(R, Theta, Phi)
                       The conversions to cartesian are:
                         X = R * Cos(Phi) * Sin(Theta)
                         Y = R * Sin(Phi) * Sin(Theta)
                         Z = R * Cos(Theta)
                       For (X, Y) equal to (1,3), Theta will be set and the abscissa 
                         and ordinates will be X and Y, respectively.
                       For (X, Y) equal to (1,2), PHI will be set.  The plot will be
                         rotated to the slice value, and the abscissa and ordinates
                         will be X and Z, respectively.  Because of the rotation, 
                         (PHI = 0) in the equation for X above.  
                     
                       ASPECT will be set unless it is explicitly unset.
                       Current version is for type 3 data only. (QS data)
           QUIET     - If set, informational messages will not be printed.
           LINESTYLE - Line type for the grid. An array may be specified to 
                     sequence over linestyles.  Lines specified by
                     LINESTYLE are: solid(0), dot(1), dash(2), dot-dash(3),
                     dot-dot-dot-dash(4), and long dash(5).
           BLOCK    - The block of data to be plotted. Default is all blocks
           COLOR    - Indicates the color of the grid, Color may be an array 
                      to sequence over colors.  If colors is an array, the
                      minimum value is 1 and the maximum is !d.table_size
                       The colors are: black(0), red(1), green(2), blue(3),
                       purple(4), orange(5), light blue(6), yellow(7) and white(8).
                      If grid is type 11 (pdb dataset) or type 10 (Exodus), then 
                      the default color is an array [1, 2, 3, 4, 5, 6, 7] and the
                      grid will be determined by the region value
                Note: Color = 0 may not be set.  Color = 0 is the default plot color.
                      Color = 9 is usually very close to 0 and my be used.
           SKIP     - The number of grid lines plotted is reduced by this value.
                      Note: If skip is very large, the blocks will be outlined.
                            (see FRAME below)
                      Currently, the first grid in a block is plotted and then
                      every lines = n*skip where n are integers.
           FRAME     - If present and not zero, will outline each block.
                     Same as skip = a very big number
           CONDUCTOR - Specifies a conductor structure or a structure array 
                       number specifying a conductor structure.  If valid, the
                       conductors will be overplotted. Colors and thicknesses
                       can be set with setdefault.
           IGNORE   - If the keyword IGNORE is set, then all previous parameters 
                      on overlay plots will be ignored.
           TITLE, XTITLE and YTITLE If grid is not zero, these will be used for
                     axis and the plot labels.  If these are not string arrays, 
                     the title, xtitle and ytitle used for the plots will be used.
           XARRAY, YARRAY, are the grid arrays for the first block plotted
           (X,Y)RANGE, STYLE, TYPE have the standard IDL meaning.
           PRINTFILE- Specifies a printfile for printing the x and y grid lines 
                      in the plot.  If PRINTFILE is not a sting, the information
                      will be sent to the screen.
                NOTE: PRINTFILE has not been implemented for POLARPLOT.
           HEADER    If specified a plot header, consisting of the current date
                     and the current file name, is displayed in the lower left
                     corner of the plot.  See the HEADER command to set default
                     HEADER parameters (character size, spacing, alignment).
                     DEFAULT is HEADER = 1
                     NOTE: For X-windows screen dumps, many will want to increase
                          the character size with the command:
                          HEADER, /set, charsize = 0.8
                          (Default is 0.6 of current size)
         LABEL_BLOCK - Label the block using XYOUTS
                     Valid values are 1, 0, -1, -2
                     1 - Label with "B #, P ##" where B and P are the block and 
                         processor numbers respectively
                         If the keyword is set and not equal a valid number, then
                         LABEL_BLOCK = 1
                     0 - No labels - DEFAULT
                    -1 - Block numbers only
                    -2 - Processor numbes only
                     If PROC is a scalar equal to zero, only blocks will be labeled
         LCHARSIZE - Charsize arguement to XYOUTS for block labels
         LCOLOR    - Color arguement for XYOUTS for block labels
         LEXTRA    - Any other keywords for XYOUTS as a structure
         SETDEFAULT- If present and not zero, then the following parameters will be
                     saved and used as the default values in all future calls to PLO
                     If a keyword is specified, it will always be used rather than
                     the saved values.
         UNSET     - If present and not zero, will set all save values of keywords
                     to their default values.
                     Normal default values are listed below.
                     Keyword     Default value
                     HEADER       1
                     XRANGE       0
                     YRANGE       0
                     ASPECT       0
    
           FILL     - Used with a pdb type grid.
                      If a structure this is passed to POLYFILL
                      (LINE_FILL, ORIENTATION, etc)
           NO_GRID  _ If set, no grid will be drawn if fill is set.
                      This is ignored if FILL is not set.
           FColor   - Fill Color
                      Default = [1, 2, 3, 4, 5, 6, 7]
                      Material region number mod n_elements(FColor) is used for 
                      the fill color index.
         SHOWDEFAULT-Show the present default plot values.
           _EXTRA    These parameters are sent to PLOT to generate the grid and 
                     can have any value appropriate for the plot command including
                     the following:
                     (X,Y)RANGE, (X,Y)STYLE, (X,Y)TYPE, POSITION , etc
                     and all have the standard IDL meaning.
     OUTPUTS:
           Designated datasets are plotted.
     EXAMPLE:
           Plot from structure g, space 1 vs space 3 with blue dashed lines
           plotgrd, g, 3, 1, color = 3, linestyle = 2
    
           Plot from structure g, space 1 vs space 3 with the fisrt line green 
           and the next 4 red. Print the values of the grid lines to the terminal.
             plotgrd, g, 3,1, color = [2,1,1,1,1], /print
    
     MODIFICATION HISTORY:
          Original version, L. P. Mix, March 25, 1993
    

    (See ../pfidl/pfidl_2d/plotgrd.pro)


    PLOTMAT

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           PLOTMAT
    
     PURPOSE:
           Plot outlines of dielectrics from TwoQuick.
         Note: This is an overplot which requires a previous PFIDL plot command
               to set the axis orientation, range, and scale.
         See also "PLOTCON, /FILL"
    
     CATEGORY:
           Visualization
    
     CALLING SEQUENCE:
    
           PLOTMAT [, Dataset] [, Color]
    
     OPTIONAL INPUTS:
           Dataset: Dataset of the dielectric data or an array of datasets
                    Dielectric data from TWOQUICK is stored as IFL data
                    Default: Dataset = 0 ; current dataset
           Color:   Color to draw the dielectric
                    Multiple values are cycled. If nc is the number of colors and
                    nd is the dataset number, then the dielectric color is:
                       dielectric_color = color[nd mod nc]
                    Default: Color = keyword(color) (see below)
    
     KEYWORD PARAMETERS:
           FILEID: File id of the PFF file
           SCALE:  If provided all spatial quanties are multiplied by SCALE[0].
                   This allows plots to use mm or cm for plot scaling.
                   Default: SCALE = 1.0
           XMUL:   Same as scale.  Provided for backward compatibility.
           LINE_FILL: If set, dielectric is filled with lines.
                   If LINE_FILL not equal to 1 then ORIENTATION = LINE_FILL.
                   POLYFILL is repeated N_Elements(ORIENTATION) Times.
                   IF LINE_FILL equal to 1 then ORIENTATION=[+45, -45]
                   Note: LINE_FILL is set if it is not zero or an array.
                   Default is solid fill or LINE_FILL =0.
           NOFill  If set, only an outline of the region will be drawn.  The
                   _EXTRA keyword applies to the IDL procedure OPLOT in this case.
           COLOR:  Color to draw the dielectric - see color above
                   If the parameter COLOR is specified the keyword is ignored.
                   Default:  Color = !p.color
           XSYM:   Make the conductor symmetric in X
                   If both XSYM and YSYM are set, a quadrant becomes 4 quadrants.
           YSYM:   Make the conductor symmetric in Y
                   If both XSYM and YSYM are set, a quadrant becomes 4 quadrants.
           Note:   If XSYM or YSYM less than zero the following quadrangs are plotted.
                   If XSYM lt 0 and YSYM eq 0 then Quadrant = 2
                                and YSYM lt 0 then Quadrant = 3
                                and YSYM gt 0 then quadrant = 2 & 3
                   If YSYM lt 0 and XSYM eq 0 then Quadrant = 4
                                and XSYM lt 0 then Quadrant = 3
                                and XSYM gt 0 then Quadrant = 3 & 4
                   Table:  Quadrants vs XSYM & YSYM
    
    							Quadrants
    				YSYM	1	2,3		1,4		1,2,3,4
    					0	2		1		1,2
    					-1	3		4		3,4
    
                         		XSYM		-1		0		1
    
           _EXTRA: Any valid keyword for POLYFILL (normal mode) or
                   OPLOT (if NOFill is set)
    
     OUTPUTS:
           Dielectric areas are drawn on the existing plot.
    
     RESTRICTIONS:
           PLOTMAT requires a previous PFIDL 2D plot command to set the axis
           orientation, range and scale.
    
     PROCEDURE:
           The dielectric data is read from the file and each dielectric is drawn.
           IF X = array of X Values for a dielectric
          and Y = array of Y Values for a dielectric then
           if keyword_set (line_fill) then
             polyfill, X, Y, col= color[nd mod nc], orientation = 45, noclip = 0, $
                 _extra = Extra_keywords
             polyfill, X, Y, col= color[nd mod nc], orientation =-45, noclip = 0, $
                 _extra = Extra_keywords
           endif else
             polyfill, X, Y, col= color[nd mod nc], noclip = 0, $
                 _extra = Extra_keywords
    
     EXAMPLE:
    
           Plot the dielectrics in dataset 9 with the standard print color.
             PLOTMAT, 9
    
           Plot the dielectrics in dataset 9 with color = 4.
             PLOTMAT, 9, 4
     or
             PLOTMAT, 9, color = 4
    
           Plot the dielectrics in dataset 9 with color = 4 and lines at +/-45.
             PLOTMAT, 9, 4 , /LINE_FILL
      or
             PLOTMAT, 9, 4 , LINE_FILL=[45, -45]
    
           Plot the dielectrics in dataset 9 with color = 4 and lines at 45 and
           linestyle = 2.
             PLOTMAT, 9, 4 , LINE_FILL=45, linestyle =2
    
           Plot the dielectrics in dataset 9 with color = 4 and horizontal lines
           and linestyle = 2.
             PLOTMAT, 9, 4 , LINE_FILL=[0], linestyle =2
    
           Plot the dielectrics in dataset 9 with color = 4 and a dot pattern
             pat= bytarr(3, 3) & pat[4]= 4
             PLOTMAT, 9, pattern= pat  ; Note: Color must be specified in pattern
    
     MODIFICATION HISTORY:
     	Written by:	David B. Seidel, 1/1/2001
    	April 12, 2001  L. P. Mix, 4/12/2001
                           Modified for inclusion in PFIDL
           May 24, 2006    L. P. Mix, 5/24/2006
                           Added XSYM and YSYM keywords to plot symmetric
                           geometries.
    

    (See ../pfidl/pfidl_2d/plotmat.pro)


    PLOTPAR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           PLOTPAR
    
     PURPOSE:
           Plot particle arrays with color weighting
     CATEGORY:
           Input/Output
     CALLING SEQUENCE:
           PLOTPAR, A [, X] [, Y] [, WT] [, YRANGE = YRANGE] [, THICK = THICK]
                [, XRANGE = XRANGE] [, COLOR = COLOR] [, TITLE = TITLE]
                [, XTITLE = XTITLE] [, YTITLE = YTITLE] [, CHANGESIGN = CHANGE]
                [, FOLLOW = follow] [, DELTA = delta] [, SYMSIZE = SYMSIZE] 
                [, PSYMBOL = psymbol] [, FAST = FAST] [, fill = fill] 
                [, POLARPLOT = polarplot] [, PTHETA = theta] [, PPHI = phi]
                [, SKIP= SKIP] [, NPARTICLE = nparticle]
                [, W1= WINDOW1] [, W2= WINDOW2] [, W3= WINDOW3]
                [, W4= WINDOW4] [, W5= WINDOW5] [, W6= WINDOW6] [, /ASPECT]
                [, XARRAY = XARRAY] [, YARRAY = YARRAY] [, FARRAY = FARRAY]
                [, OVERPLOT = OVERPLOT]  [, IGNORE = ignore]
                [,CONDUCTOR = CONDUCTOR] [, GRID = GRID]
                [, RESULT = result] [, QUIET= quiet] [, VECTOR = vector]
                [, HEADER = header] [, SETDEFAULT = setdefault] [, UNSET = unset]
                [, BIN = bin] [, XBIN = xbin] [, YBIN = ybin] [, NGP = ngp]
                [, SHOWDEFAULT = showdefault] [, THERMOMETER = thermometer]
                [, ZRANGE = zrange] [, ZTYPE = ztype] [, /LEFT] [, /RIGHT]
                [, ZPLANE = zplane] [,_EXTRA = extrastuff]
     INPUTS:
           A     IDL particle structure (type = 2)
           X     Abscissa values (positive = x array, negative = attribute array)
           Y     Ordinate values (positive = x array, negative = attribute array)
           WT    Weight array  (positive = x array, negative = attribute array)
                 ZRANGE is used to scale WT
                 If log scaling, the absolute value of zrange is used and the log taken.
                 ZTYPE is used to select log scaling for WT
         NOTE: If x, y, or wt is an array, then the square root of the sum of 
                 the squares will be used unless the value is identical
                 For example:
                 If X = [1, 2, 3] for a cartesian system, then the abscissa will
                    be the radius.  Abscissa is SQRT(A.X1^2 + A.X2^2 + A.X3^2)
                 If X = [1] then the abscissa is ABS(A.X1) 
                 if X = [-4] then the abscissa is ABS(A.V4) (the 4th attribute)
         NOTE: If overplot is not zero, then x and y can be determined from the
               previous plot if they not specified. WT will be the second parameter.
    
     KEYWORD PARAMETERS:
           PSYMBOL  - Symbol type - Default is is a filled circle unless 
                      Fast is set. If Fast is set, a triangle will be used.
                      The symbol is defined by PSYMBOL: (1)plus sign, 2(asterisk),
                      3 (period), 4 (diamond), 5 (triangle), 6 (square), 7 ("X").
                      (If the symbol value is greater than 10 then ll will be
                      subtracted from the value and MKSYMBOL will be called.)
                      (0),Square; (1),Circle; (2),Triangle; (3),Diamond;
                      (4),Big X; (5),Delta; (6), Star; (7),Plus; (8),Hexagon;
                      (9),Pentagon; (10), Clover; (11),PACMAN; (12),Spiral
                      Note: Symbols may also be specified as names:
                        Follow ='sq' or 'ci' or 'diamond' or 'clover']
                        These will be converted to numbers: 11 or 12 or 14 or 21]
           FAST     - Indicates a fast plot is desired.  If PSYMBOL is not
                      specified and fast is not zero, a triangle will be used.
                      FILL is set to zero.
           FILL     - If set filled symbols will be used if available.
                      (Applies to symbols 11 and above)
           OVERPLOT - If not zero, indicates no new grid is to be drawn.
                      If OVERPLOT is set, it will have a value of 1 on return.
                      If not set, OVERPLOT will be have a value of zero on return.
                      OVERPLOT will be set to zero or one on return.
           IGNORE   - If set and an overplot, ignore the previous values.
                      If IGNORE is set, it will have a value of 1 on return.
                      If not set, IGNORE will have a value of zero on return.
           SYMSIZE: - Symbol size multiplier - Default is 0.5
           ASPECT   - If set, the ordinate and abscissa will have the same 
                      relative scaling.
           COLOR    - If wt has fewer elements than the x and y arrays, then
                       the points will be drawn using color = color. 
                       The colors are: black(0), red(1), green(2), blue(3),
                       purple(4), orange(5), light blue(6), yellow(7) and white(8).
           CHANGESIGN - If change is present and not zero, wt = -wt
           ZRANGE   - Range of WT scaling - This must be a two element vector.
                      ZRANGE = [ WTmin, WTmax ] 
           ZTYPE    - If set, use log scaling for WT.
                      If negative, then 
                        M = max(wt)
                        wt = log (wt > abs(ztype)*M)
                      If ZTYPE gt 0 then ZTYPE = -(1e-4)
           THERMOMETER - If set a thermometer will be generated.
                         If a structure, then it will be passed to thermometer 
                          routine.
                     Note: Used only for a weighted particle plot.
                           If set, then OVERPLOT is set to zero
           SKIP     - The total number of points plotted is reduced by this value.
                      unless follow is set.  If follow is set, skip is used as 
                      a skip factor in a loop over trajectories.
                      If skip less than zero then n/skip particles will be plotted.
           W1, W2, W3, W4, W5, W6  - Each is an array of 3 or more elements. 
                     Plot can be windowed in real space or attribute space
                     Last two values in the array are the minimum and maximum 
                     values of the window parameter; the first value(s) are the 
                     spatial or attribute parameters to be used for the window.
                     The criteria is: {min <= (value) <= max}
    
                     Note: If W has 4 elements then:
                         a.  If W[0] eq W[1] then the absolute value of W[0] will
                               be windowed.
                         b.  If W[0] ne W[1] then the square root of the sum of the
                               squares will be windowed.
           CONDUCTOR - Specifies a conductor structure or a structure array 
                       number specifying a conductor structure.  If valid, the 
                       conductors will be overplotted.  Colors and thicknesses
                       can be set with setdefault.
                       Use ZPLANE to set the normal plane value.
           ZPLANE    - Value of the third dimension for the CONDUCTOR and GRID
                       plots. Default: Middle of data range - for particles this
                       may not be the middle of the problem range.
           POLARPLOT - If set, a polar plot will be generated.
                     For the SPARE[0] eq 1, no polar plot is generated
                     The coordinates for cylindrical and spherical data are as follows:
                       R     - Radius vector
                       PHI   - Angle between the radius vector projected on the X-Y 
                               plane and the X axis
                       Z     - Axis normal to the X-Y plane
                       THETA - Angle between the Z axis and the Radius vector.
                     For the SPARE[0] eq 2, the cylindrical data will be converted
                       to cartesian and plotted; Coordinates=(R, Phi, Z)
                       X and Y must be 1 and 2 in any order, but they will be
                         set to 1 and 2 respectively.
                       The conversions are:
                         X = R * Cos(Phi)
                         Y = R * Sin(Phi)
                     For the SPARE[0] eq 3, the spherical data will be converted
                       to cartesian and plotted; Coordinates=(R, Theta, Phi)
                       The conversions to cartesian are:
                         X = R * Cos(Phi) * Sin(Theta)
                         Y = R * Sin(Phi) * Sin(Theta)
                         Z = R * Cos(Theta)
                       For (X, Y) equal to (1,3), X and Y will be calculated according
                         to the equations above and will be plotted with THETA = (!pi/2)
                         If THETA is defined, then the equation for X will use:
                           X = R * COS(X3) * SIN(X2 - THETA)
                           where X2 is the second dimension, theta.
                       For (X, Y) equal to (1,2), PHI will be set depending on the 
                         keyword PPHI.
                       If PHI is undefined.  Each point will have a value of PHI =0. 
                         The abscissa and ordinates will be X and Z, respectively.
                         X = R * SIN(X2)
                         Z = R * COS(X2)
                       If PPHI is defined, the plot will use:
                         X = R * COS(X3 - PPHI) * SIN(X2)
                         where X2 and X3 are the second and third coordinates.
                       ASPECT will be set unless it is explicitly unset.
                       Current version is for type 2 data only.
           PTHETA  - See POLARPLOT
                     Used only if POLARPLOT is set and [X,Y] = [1,3]
           PPHI    - See POLARPLOT
                     Used only if POLARPLOT is set and [X,Y] = [1, 2]
           NPARTICLE - Number of particles plotted in a standard particle plot
                       is returned
           Verbose   - If set, NPARTICLE is printed to the terminal
           FOLLOW  - If a particle dataset represents the motion of a test particle,
                     the follow command allows the orbit in one plane to be mapped.
                     This keyword will be ignored if the number of attributes is
                     less than 1.
                     No symbols are plotted. The linestyle is given by 
                     abs(follow -1) mod 6 (If /follow is used, linestyle is solid.)
           DELTA   - Indicates a symbol is to be plotted on the curve at
                     approximate increments given by delta. Ignored if FOLLOW=0
                     If delta is less than zero, then all points will be plotted.
                     If the number of attributes is 6, then attribute 4 will be
                     used; otherwise the number of attributes -1 will be used.
                     A maximum of 2 symbols per point will be used.
           GRID    - Specifies a grid structure or a structure array number.
                     If valid, the grid will be overplotted.  Color and 
                     thickness can be set with setdefault.
                     Use ZPLANE to set the normal plane value.
     (window parameter is positive = spatial array, negative = attribute array) 
     (in the case of multiple parameters, use the sq root of the sum of the squares)
           TITLE, XTITLE and YTITLE If grid is not zero, these will be used for
                     axis and the plot labels.  If these are not string arrays, 
                     the title, xtitle and ytitle used for the plots will be used.
           XARRAY, YARRAY, FARRAY are the arrays sent to PLOTWT for the actual 
                     particle plots unless BIN ne 0
           BIN       If present and not zero, then XARRAY, YARRAY and FARRAY become
                     X and Y coordinates for a contour plot and the actual function.
                     ie: "contour, farray, xarray, yarray" would produce a contour
                     plot of the particle density.  If WT is the particle charge,
                     then FARRAY is the charge density. If WT is absent, then FARRAY
                     is the number density.
                     NOTE:  If RESULT is a valid structure, then FARRAY, XARRAY, 
                            and YARRAY will be put into structure = RESULT
                     NOTE: FARRAY is normalized to the area of the bin.
                           For Cartesian this is simply DX*DY
                           R and R^2 sin(theta) scaling are included with 
                           cylindrical and spherical coordinates.
                     CAUTION: For a cylindrical plot with theta, Z, the radius in
                              NOT included in the normalization.
                     If BIN is less than 0 then XARRAY and YARRAY will be used for
                       bins for the particles. (XARRAY and YARRAY may have arbitrary
                       spacing.)
                     Note: BIN less than zero is about 50% slower than a uniform
                           bin.  Errors can be as large as over 1e-5 for a 64x64 
                           bin but about 1e-7 for a 65x65 grid; that is  the
                           spacing is not a reciprocal power of 2.
                           Time is about 4 minutes/million particles for uniform, 
                           ie, bin > 0 or 6 minutes/million for bin< 0.
                     If BIN is less than 16 then a uniform 65x65 grid will be 
                       established for FARRAY (64 cells, 65 grid lines).
                     If BIN is 16 or larger then a BINxBIN grid will be established
                       for FARRAY.
           XBIN, YBIN  - These values if present will override the values in BIN
                     nx = abs(xbin)> 3  
                     ny = abs(ybin)> 3 
                     If xbin and ybin are greater than zero, then bin will be set.
                     Bin must be greater than zero if only xbin or ybin is set.
           NGP       If set the number of X and Y BIN values is reduced by 1.
                     The BIN values will be taken as boundaries of each cell.
                     This is ignored if BIN =0, and either XBIN or YBIN is zero.
                     Default is NGP =0
                     If NGP = 0, values will be interpolated to the four closest 
                       grid points.
                     If NGP is not zero, values will be credited to the square in
                       which they fall. And the X and Y values will be changed to
                       the center of each grid after particles are sorted. This
                       reduces the number of x and y values by 1.
             Note: NGP is slightly faster than interpolation however the 
                     errors can be much larger. Speed is about 100 sec/Million
                     and 4 minutes /million for bin >0 and <0
           Vector    If present and not zero then FARRAY will be used to store
                     the specified quantity according to the following scheme:
                     0 - Particle density or charge density
                     1 - Px or charge weighted value of Px
                     2 - Py or charge weighted value of Py
                     3 - Pz or charge weighted value of Pz
                     Note: Particle must have as many attributes as value of VECTOR
                     Default is VECTOR = 0
               NOTE: With a weight of -4 and a vector value of 1, the value 
                     in farray will be proportional to the charge current density
                     in the x direction; with a weight of 0 farray will be 
                     proportional to the particle current density
           RESULT    If present and a valid structure array number, the xarray, 
                     yarray, and farray data from the bin command will be sent to 
                     this structure array.
           QUIET   - If present and not zero,level information will not be printed.
                     If quiet has a value of 1 (/QUIET or QUIET =1), NO plots
                     will be make.  If QUIET is not zero and not 1, then plots
                     will be made, but no output to the terminal.
                     Default: QUIET = 0
           HEADER    If specified a plot header, consisting of the current date
                     and the current file name, is displayed in the lower left
                     corner of the plot.  See the HEADER command to set default
                     HEADER parameters (character size, spacing, alignment).
                     DEFAULT is HEADER = 1
                     NOTE: For X-windows screen dumps, many will want to increase
                          the character size with the command:
                          HEADER, /set, charsize = 0.8
                          (Default is 0.6 of current size)
         SETDEFAULT- If present and not zero, then the following parameters will be
                     saved and used as the default values in all future calls to PLO
                     If a keyword is specified, it will always be used rather than
                     the saved values.
         UNSET     - If present and not zero, will set all save values of keywords
                     to their default values.
                     Normal default values are listed below.
                     Keyword     Default value
                     HEADER       1
                     XRANGE       0
                     YRANGE       0
    
         SHOWDEFAULT-Show the present default plot values.
           LEFT     Indicates a new plot using the left axis.
                    A single axis will be drawn on the left side of the grid
                    For this plot XMARGIN will be set to
                       XMARGIN = [!X.margin(0), !X.margin(0)]
                    and YSTYLE = 8.
                    NOTE: If LEFT is set, OVERPLOT is set to 0.
          RIGHT     Indicates a OVERPLOT making and using the right axis.
                    If RIGHT is present and not zero, then:
                      A single axis will be drawn on the right side of the existing
                        grid
                      The particle data will be overplotted on the existing grid.
                    Before using this command, a plot should be created using
                      the keyword: /LEFT
                    NOTE: If RIGHT is set then OVERPLOT is set to 1.
                    NOTE: After this command all memory of the original y-axis
                          scaling is lost
           _EXTRA    These parameters are sent to PLOTWT and can have any value 
                     appropriate for the plot command including the following:
                     (X,Y)RANGE, (X,Y)STYLE, (X,Y)TYPE, LINESTYLE, POSITION , etc
                     have the standard IDL meaning.
     OUTPUTS:
           Designated datasets are plotted.
     EXAMPLE:
           Plot from structure a, space 1 vs space 3 with attribute 4 
             as the weight and use a grid [0,0.064, 0, 0.14]
           plotpar, a, 3, 1, -4, xrange = [0,0.064],yrange = [ 0, 0.14]
    
           Plot from structure a, the sum of the squares of attributes 1 and 3 
             vs space 3 with attribute 4 as the weight
           plotpar, a, 3, [-1,-3], -4
    
           Plot from structure a, space 1 vs space 3 and limit the plot to values
             of space 2 in the range [0, 3]  with attribute 4 as the weight and 
             overplot conductors in datasets 3 and 4
           plotpar, a, 3, 1, -4, w1 =[3, 0, 3], cond= [3,4]
    
           Plot a particle structure 1 with a thermometer. Label the thermometer Q
           Plot z-r and color the particles with charge scaled by -1.
             plotpar, 1, 3, 1, -4, /change, thermometer= {title:'Q'}
    
           Same as before, but color the particles with the absolute value of the charge
             plotpar, 1, 3, 1, [-4], thermometer= {title:'Q'}
    
           Overplot a particle plot, with attribute 4 as a weight and the 
           conductors in structure, c2.
           plotpar, a, -4, /over, con = c2
    
           Plot from structure a, space 1 vs space 3 with a window of energy of 
             1e10 to 1e13 for the magnitude of the momentum in attributes [1,2,3]
             with attribute no weight
           plotpar, a, 3, 1, w1 =[-1, -2, -3, 1e10, 1e13]
    
     MODIFICATION HISTORY:
          Original version, L. P. Mix, March 5, 1993
    

    (See ../pfidl/pfidl_2d/plotpar.pro)


    PLOTSTR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           PLOTSTR
    
     PURPOSE:
           Plot a structure array
           WARNING:  The maximum structure array will be used as a working 
                     structure array for PLOTFLD
           For a description of parameters and keywords, see the commands
              PLOTFLD
              PLOTCON
              PLOTGRD
              PLOTPAR
     EXAMPLE:
           Contour plot of the charge density, in structure F, from a 2-D calc.
             plotstr,  f
    
           Contour plot of the charge density, in structure array 2, from a 3-D 
           calculation taking a slice for the second dimension equal to 0.0
             plotstr, 2,1, 2, 0.0
      (or)   plotstr, 2,   2, 0.0 (since only one attribute, 1 can be omitted)
    
           Plot from structure g, space 1 vs space 3 with blue dashed lines
           plotstr, g, 3, 1, color = 3, c_line = 2
    
           Plot from structure array 2, space 1 vs space 3 
                 use a grid [0,0.064, 0, 0.14]
           plotstr, 2, 3, 1, xrange = [0,0.064],yrange = [ 0, 0.14]
    
    
    
     MODIFICATION HISTORY:
          Original version, L. P. Mix, March 15, 1993
    

    (See ../pfidl/pfidl_2d/plotstr.pro)


    PLOTVEC

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           PLOTVEC
     PURPOSE:
           Make a vector plot from two single block field structures
             or from two attributes in a single block field structure      
           Note: If aspect ratio of the X and Y ases are not nearly equal
                 then care must be exercised in in interpreting the vectors 
                 as (R, theta).  For example if the x axis goes from 0 to 10
                 and the y axis goes from 0 to .1 then almost all the vectors 
                 will be vertical on this plot.
                 Use the rtheta keyword to get an r-theta plot. That is with
                 equal field components the vector will be at 45 degrees.
     CATEGORY:
           Graphics
     CALLING SEQUENCE:
           PLOTVEC, STR1 [, STR2]
           PLOTVEC, STR1 [, VECTORS]
     INPUTS:
           STR1:    array or array number of the first field structure array 
                  - this must be two dimensional or three dimensional with 
                    a degenerate dimension and a single block.
                    If STR2 is given then STR1 must be a scalar field.
                    If STR2 is not given then STR1 must have 2 or more components.
           STR2:    array or array number of field structure to be plotted with 
                    the first structure
                  - this must be two dimensional or three dimensional with 
                    a degenerate dimension, a single block, and have a scalar field.
      or
           VECTORS  array of two elements indicating the vector components to be 
                    used for the X and Y components of the vector plot 
                    Default value is the components corresponding to the 
                    nondegenerate dimensions.
    
     KEYWORDS:
           ASPECT:  If set, aspect ratio is 1:1
                    Default is ASPECT =1
           CUBIC:   If set, use cubic interpolation
           XRANGE:  Range of X-values of interest for the plot
           YRANGE:  Range of Y-values of interest for the plot
           ZRANGE:  Range of Vector amplitudes of interest
                    Default for XRANGE, YRANGE and ZRANGE is the range of the 
                      actual data unless ZLOG is set.  If the number of elements
                      of each is less than 2, the actual values will be returned.
                    If ZLOG is set and ZRANGE has no elements then:
                      ZRANGE(0) > 1.0e-3* (Maximum(VECTOR) = ZRANGE(1))
                    If ZLOG is set and ZRANGE has one element and that element is 
                      greater than zero and less than 1 then it will be used to 
                      scale the minimum value for the log plot
                      ZRANGE(0) = (ZRANGE)* Maximum(VECTOR)
                    IF ZRANGE has 2 elements then the range will be between these
                      two values.
                    If ZRANGE has 1 element and is equal to 1 then if the vectors 
                      are from a single structure, zrange will be set to
                        ZRANGE = [min(sqrt(v1*v1+v2*v2), max = mm), mm]
                      where v1 and v2 are the vectros used for the vector plot.
                      Currently, xrange and yrange are ignored.
                    Alternatively if you are doing:
                         plotstr, 1, [1,2], cn=2, zrange= zrange
                         plotvec, 1, [1,2], zrange = zrange 
                    then both plots will have the same min/max scaling.
           ARROW:   If present and not zero, vectors will be indicated with an
                    arrow. (based on USERLIB routine, VELOVECT)
                    Default is ARROW =1; vectors indicated with a spot and bar.
           FILL:    Make a solid arrow head.
           RTHETA:  Make an R-THETA plot so that the angle of the vector depends 
                    on the relative magnitude of the fields and may not be the 
                    actual direction of the field
           LENGTH:  Length factor in units of the point spacing (see BIN)
                    If length is negative, then all bars/arrows will be the same
                    length given by abs(length). Magnitude can be shown with color
                    Default is length = 1
                    NOTE: If length is negative and the magnitude of the vector is
                    less than 2^(-14) (ie, 6.10e-5) of the maximum amplitude, then
                    the vector will be zero length.
           BIN:     Number of points in the horizontal and verticle direction.
                    If BIN is a vector then the [BIN(0), BIN(1)] are the number
                    in the horizontal and vericle direction.  If BIN is a scalar,
                    Then that number will be used for the longest direction; the 
                    same bin size will be used for then transverse direction.
                    Default is BIN = 30 .
           THICK:   Thickness of the arrow or bar used for the vector. 
                    Thick is multiplied by !p.thick> 1
                    Default is 1
           SYMSIZE: Size of the spot used for the vector origin if ARROW = 0
                    Default is 0.75
           COLOR:   Array of colors for the vectors lines. 
                    If color is an array those colors will be used to quantify 
                      the amplitudes
                    If color is not an array, then 
                      If color = -1 then colors will go from 9 to !d.table_size
                        uniformly spaced using the existing color table
                        (if ZLOG is set the applitude will be logarithmic)
                      If color is positive, that color will be used for all 
                        contours, [1, 7] are the primary colors, 9 to !d.table_size
                        depend on the color map.
                      Color = 0 is the default plot color (ie, white or black)
                        which is set by the system parameter, !P.COLOR
                    Default is set by SETDEFAULT or QSINIT
                    The colors are: red(1), green(2), blue(3),
                    purple(4), orange(5), light blue(6), yellow(7).
           TITLE:   Title for the plot; Default is a combination of the attribute
                    or vector labels.
           TRANSPLOT:If present and not zero, interchange ordinates and abscissa
                    SETDEFAULT can be used to set a default value
                    NOTE: This only switches spatial coordinates.  To switch
                          vector coordinates, interchange the two vector components
                          or the two structures.
           OVERPLOT:If present and not zero, plot the vector plot on the 
                    current plot. Default is overplot =0
           IGNORE:  If present and not zero, ignore the parameters from the previous
                    plot if this is an overplot.
           BORDER:  If present and not zero, add a border to XRANGE and YRANGE 
                    given by BORDER*LENGTH*point spacing. XSTYLE and YSTYLE if 
                    not set are set to 1.
           X(Y)BORDER: Ignored if border is set. This is the same as border but it
                    only applies to the X (or Y) axis 
           ZLOG:    If present and not zero, a log scale will be used for the color
                    map and magnitude.  Default is ZLOG = 0
                    ZLOG = 0 scaling:
                      length = (magnitude-level(0))/(level(1)-level(0))*max_length
                    ZLOG = 1 scaling:
                      replace magnitude with ALOG(magnitude)
                      replace level with ALOG(level)
           HEADER   If specified a plot header, consisting of the current date
                    and the current file name, is displayed in the lower left
                    corner of the plot.  See the HEADER command to set default
                    Note: File name is taken from the first structure (STR1)
                    HEADER parameters (character size, spacing, alignment).
                    DEFAULT is HEADER = 1
                    NOTE: For X-windows screen dumps, many will want to increase
                          the character size with the command:
                          HEADER, /set, charsize = 0.8
                          (Default is 0.6 of current size)
        THERMOMETER- If keyword is set a thermometer will be generated
                     with the vector plot.
                     Default IDL margins are [10, 3] for x and [4, 2] for y
                     If TPARAM does not have a Tag Name beginning with 'CU'
                     then:
                     If no tag names begin with 'H' xmargin will be set to
                       [!x.margin(0), 10]
                       otherwise ymargin will be set to [8, !y.margin(1)]
               Note: xmargin or ymargin passed to plotfld will override
                           these settings.
               Note: If THERMOMETER is a structure, then TPARAM is ignored
                     and set equal to THERMOMETER
           TPARAM  - Structure containing data for the thermometer, Tag names
                     must be valid for the THERMOMETER procedure.
    
         SETDEFAULT-If present and not zero, then the following parameters will be
                     saved and used as the default values in all future calls to PLO
                     If a keyword is specified, it will always be used rather than
                     the saved values.
         UNSET     - If present and not zero, will set all save values of keywords
                     to their default values.
                     Normal default values are listed below.
                     Keyword     Default value
                     ARROW        1
                     THICK        1
                     BIN          [30, 30]
                     XBORDER      0
                     YBORDER      0
                     LENGTH       1.0
                     HEADER       1
                     XRANGE       0
                     YRANGE       0
                     ZRANGE       1.0e-3
                     SYMSIZE      0.75
                     THERMOMETER  0
         SHOWDEFAULT-Show the present default plot values.
                    
           _extra:  Any additional keywords understood by the plot command.
                    This keyword is ignored if overplot is not equal to zero.
     OUTPUTS:
           Vector plot of the designated field values.
     PROCEDURE:
           This routine is based on VELOVECT.  Two options exist for the vector:
           1. A spot with a bar going in the direction of the vector.
           2. An arrow going in the direction of the vector.
           If length is negative, all arrows/bars will be the same length.
           If color is -1, then the arrows/bars & spots will be colored according
             to their length and the existing color map.
    
     EXAMPLES:
           Structure array 2 has a degenerate middle dimension and 3 components of 
             the electric field.  Make a vector plot of the first and third 
             components of the electric field and make a plot of the first and
             second components of the field.
                   PLOTVEC, 2  (Components default to [3,1])
                   PLOTVEC, 2, [2,1]
    
           Structure array 2 has the radial component of the electric field and
           structure array 5 has the azial component of the electric field; the 
           sturctures are degenerate in the theta direction. Make a vector plot
           of these field values.
                   PLOTVEC, 5, 2
           
           Structure 3 is a 3D, multiblock electric field structure. In the plane 
           Theta = [0,1], plot the x and y components of the electric in a vector
           plot with arrows. Use structures 5 and 6 as working sturctures.
           Note: If only a limited portion is of interest for the vector plot, 
           use xrange, yrange, or block keywords to limit the region in the result
           structures.
                 PLOTSTR, 3, 3, 2, [0, 1], cn=2, result =5
                 PLOTSTR, 3, 1, 2, [0, 1], cn=2, result = 6
                 PLOTVEC, 5, 6, /arrow
           To obtain a background with a contour plot use 
                 PLOTSTR, 3, [1,3], 2, [0, 1], cn=2
                 PLOTVEC, 5, 6, color= 4, /over, /ignore, /arrow, leng = -0.75
    
     MODIFICATION HISTORY:
          Original version, L. P. Mix, April 29, 1994
    

    (See ../pfidl/pfidl_2d/plotvec.pro)


    PLOTWT

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           PLOTWT
    
     PURPOSE:
           Plot two arrays with color weighting
     CATEGORY:
           Input/Output
     CALLING SEQUENCE:
           PLOTWT, X, Y, WT, [, PSYMBOL = PSYM] [SYMSIZE = SYMSIZE] 
               [, OVERPLOT = OVERPLOT] [, COLOR = COLOR] [, TITLE = TITLE]
               [, XRANGE = XRANGE] [, YRANGE = YRANGE] [YSTYLE = YSTYLE]
               [, XSTYLE = XSTYLE] [, XTYPE = XTYPE] [, FAST = FAST]
               [, XTITLE = XTITLE] [, YTITLE = YTITLE]  [, QUIET = quiet]
               [, THERMOMETER = thermometer] [, ZRANGE = zrange] [, C_RANGE= c_range]
               [, /LEFT] [, /RIGHT] [, ASPECT = ASPECT] [, ZTYPE = ztype]
               [, _EXTRA = extrastuff]
     INPUTS:
           X:        Abscissa values
           Y:        Ordinate values
     OPTIONAL INPUT:
           WT:       Weight array used to determine color or the points
                     Note: If electron charge is used, use -wt.
                     Default - WT is 1
                     ZRANGE keywork applies to wt
     KEYWORD PARAMETERS:
           ZRANGE    Scaling range for WT
                     If log scaling, the absolute value is used and the log taken.
           ZTYPE     If set, WT scaling is logarithmic
                     If negative, use it to determine the minimum for log scaling
                        M = max(wt)
                        wt = log (wt > abs(ztype)*M)
                     If ZTYPE gt 0, then ZTYPE = -(1e-4)
           THERMOMETER If set a thermometer will be generated.
                       Ignored if no weight is specified.
           Note: THERMOMETER must have a non-zero range for either WT or ZRANGE
           PSYMBOL      Symbol type - Default is 8 or 5 (see FAST)
           FAST      Indicates a fast plot is desired.  If PSYMBOL is not 
                     specified and fast is not zero, a triangle will be used.
           SYMSIZE:  Symbol size multiplier - Default is 0.3
           OVERPLOT  If not zero, indicates no new grid is to be drawn.
           COLOR     If wt has fewer elements than the x and y arrays, then
                     the points will be drawn using color = color. 
                       The colors are: black(0), red(1), green(2), blue(3),
                     purple(4), orange(5), light blue(6), yellow(7) and white(8).
                     If color eq 0 then color = !p.color
           (X,Y)RANGE, STYLE, TYPE have the standard IDL meaning.
           TITLE, XTITLE and YTITLE If grid is not zero, these will be used for
                     axis and the plot labels.
           C_RANGE:  Two element vector specifying the range of the color table to
                     use for CNTOUR = 1,2.
                     First number is the lower value, and second is the upper
                     value expressed as a fraction of full scale.
                     Default: C_RANGE=[0,1] = [9, !d.table_size-2]
                     Alternatively, elements of the color table can be specified.
                     If max(C_RANGE) gt 1 then elements are assumed.
                     The first number should be ge 9 and the second number should
                     be le (!d.table_size-2) if not they will be changed.
           LEFT     Indicates a new plot using the left axis.
                    A single axis will be drawn on the left side of the grid
                    For this plot XMARGIN will be set to
                       XMARGIN = [!X.margin(0), !X.margin(0)]
                    and YSTYLE = 8.
                    NOTE: If LEFT is set, OVERPLOT is set to 0.
          RIGHT     Indicates a OVERPLOT making and using the right axis.
                    If RIGHT is present and not zero, then:
                      A single axis will be drawn on the right side of the existing
                        grid
                      The particle data will be overplotted on the existing grid.
                    Before using this command, a plot should be created using
                      the keyword: /LEFT
                    NOTE: If RIGHT is set then OVERPLOT is set to 1.
                    NOTE: After this command all memory of the original y-axis
                          scaling is lost
           QUIET   - If present and not zero,level information will not be printed.
                     If quiet has a value of 1 (/QUIET or QUIET =1), NO plots
                     will be make.  If QUIET is not zero and not 1, then plots
                     will be made, but no output to the terminal.
                     Default: QUIET = 0
           ASPECT  - If set, the ordinate and abscissa will have the 
                       same relative scaling.
           _EXTRA   Structure sent to the plot command using the _EXTRA keyword
    
     OUTPUTS:
           Designated datasets are plotted.
     EXAMPLE:
           Plot Y versus X with Charge used as a weight
           plotwt, x, y, charge
    
     MODIFICATION HISTORY:
          Original version,  L. P. Mix, March 5, 1993
          September 15, 2005 Added ZRange and ZType to scale the amplitude
          November 20, 2005  P. Leyde modified to draw when wmin = wmax and zrange not specified.
    

    (See ../pfidl/pfidl_2d/plotwt.pro)


    PUT_ARRAY

    [Previous Routine] [Next Routine] [List of Routines]
       This procedute puts an array into a structure
       The dimensions of the array must be identical to the existing vector
          which it replaces.
       Format: PUT_ARRAY, Structure, Vector, Space [, Block] [, label= lab] 
                           [, /ALLDATA] 
       where: Structure - IDL structure name or structure array number
                          type must be 1, Field
                                       2, Particle
                                       3, Grid
                                       8, Finite Element Time Sliced
                                       9, Finite Element
        Note:  Type 8 and 9 data requires that the ALLDATA keyword is set
               If not set, it will be set silently.
              Vector- Vector to be inserted into structure.  It must be identical
                      to the vector it replaces.
              Space - If greater than zero, indicates spatial dimension desired
                      If negative, indicates field data or attribute data.
              Block - Indicates block - not used for particle data
                      Default: BLOCK = 1
              Label - Attribute label or block label associated with this data
                      Default:  lab  = 'Modified value'
              ALLDATA - Ignored - present for backward compatibility
                      This parameter is not required. If the number of elements in 
                      Vector is equal to the number of elements for all blocks, 
                      ALLDATA will be set automatically. 
        Examples:
          Calculate the SIN of the third component of structure 1 for all blocks
            IM = GET_ARRAY(1, -3, /ALL) 
            IM = SIN(IM)
            PUT_ARRAY, 1, IM, -3
    
          Scale the values in an image in array 2 with polynomial coefficients COEF
          and store the result in array 3
            IM = GET_ARRAY(2, -3, /ALL) 
            IM = POLY(COEF, IM)
            XFRSTR, 2, 3
            PUT_ARRAY, 3, IM, -3, LAB= 'Image scaled by fit #2'
    
    

    (See ../pfidl/pfidl_2d/put_array.pro)


    READEMPH

    [Previous Routine] [Next Routine] [List of Routines]
    
      Reads a Emphasis GRID dataset and conductor information into IDL structures.
    
      Format:  READEMPH [, STRUCTURE] [, FILENAME] [, FILENAME = filename]
                        [, PROCESSOR = processor] [, /GHOST] [BLOCKS = blocks]
    
      where:
        STRUCTURE - QS structure array number or an array of 3 numbers
        Note: If the parmeter FILENAME is a File ID then Structure must be provided
                    Default = [1, 2, 3, 4]
                    If one number is give, then 
                    Default = structure[0] + indgen(3)
                    STRUCTURE[0] = Grid structure with the full grid values
                                   Blocks are the original problem blocks
                    STRUCTURE[1] = Field structure with the half grid and material
                                   numbers for the field values
                    STRUCTURE[2] = Grid structure with the full grid values
                                   in each decomposed blocks. 
                                   If a serial run, then STRUCTURE[2] is not saved.
                    STRUCTURE[3] = Grid structure with the half-grid values
                                   in each decomposed blocks and the material 
                                   number for the field values
                                   If a serial run, then STRUCTURE[3] is not saved.
        FILENAME  - Name of file containing the Emphasis/Nevada grid information
            NOTE:  Structure must be provided is FILENAME is a PFF File ID.
                    FILENAME may be the second parameter or a keywork.
                    If FILENAME parameter is missing or zero, the keyword 
                      FILENAME is checked.
                    If FILENAME is still not defined, DIALOG_PICKFILE is called.
                    If FILENAME is a number, not equal to zero, then FILENAME is
                      the file ID of the desired PFF file.  If it equals zero, then
                      DIALOG_PICKFILE is used to determine the file. 
                    If the file id is specified then the dataset pointer should 
                      be at a IFL dataset type with a comment "Buffer Planes"
                      The routine will look for a dataset with this comment, and
                      continue if only one is found.
        PROCESSORS - Returns the number of processors
        BLOCKS    - Returns the processor for each decomposed block
                    BLOCKS = 0 for a single processor problem
        GHOST     - If set, ghost cells will be included.
                    If GHOST is a vector then the first element applies to 
                      STR[0] and the second to the material structures, 
                      STR[1] and STR[2]
    
      Structure Labels
        type  - 3
        ndim  - number of spatial dimensions = 3
        block - number of blocks 
        size  - array of the size of the spatial dimensions
                size = size(ndim, block)
        two   - two dimensional missing dimension
                this is 0 for 3d data, 1 for yz data, 2 for zx data, 3 for xy data
        range - (2, ndim, nblock+1) two dimensional array of the max and min for
                each block.  Block (0) has overall values.
        locx  - array of the location of the first point for each block
                spatial array- locx = locx(ndim, block+1)
                (first spatial dimension for block m is x and is defined by
                 x = x1(locx(0, m-1): locx(0, m)-1) )
        x1, x2, x3 - spatial arrays
        proc  - Processor number if available on parallel jobs
        x1lab, x2lab, x3lab - spatial labels
        tlab  - type label
        clab  - dataset comment
        PROC  - Block Processor number
        file  - file data read from
        spare - integer array (5)
    
      Examples:
        Read Emphasis/Nevada grids from 'My_data.pff', into arrays 1,2,3
          READEMPH, 'My_data.pff'
        Read Emphasis/Nevada grids from 'your_data.pff', into arrays 1,34 ,300
          READEMPH, [1, 34, 300], 'My_data.pff'
        
    

    (See ../pfidl/pfidl_2d/reademph.pro)


    READRAW

    [Previous Routine] [Next Routine] [List of Routines]
        Read an image array from a RAW image file
        Image is stored as two-byte binary integers
    
        format is:  READRAW [, FNAME] [, STR]  [, /HELPME] 
                            [, CLabel = clabel] [ /INTEGER]
                            [,  XSIZE = xsize [, YSIZE = ysize]
        where 
          fname   - the file name
                    If fname = 0 or undefined then dialog_pickfile() will 
                    be used to select a file
          STR     - STR array or STR array number
                    If STR is not provided, then an unused structure array
                    will be used.
          HELPME  - If set, a help statement will be printed.
          CLABEL  - If set used as the label for the structure.
                    Default:  'Raw Image - ' + fname
          INTEGER - If set, save the image as an integer array
          XSIZE   - Number of pixels in the horizontal direction
                    Default: XSIZE = 2048
          YSIZE   - Number of pixels in the vertical direction
                    Default: YSIZE = 2000
     PROCEDURE:
          Open a file and read the data as an integer.  Swap the byte order
          if working on a little endian computer.
    
        Example:
        Read STR array 5 from file 'PFIDLdefault.dat'
           READRAW, 'PFIDLdefault.dat' , 5
    
        Resd STR 3 from a file to be selected from Dialog_Pickfile()
           READRAW , 0, 3
    
     MODIFICATION HISTORY:
          Original version, L. P. Mix, October 2, 2006
    

    (See ../pfidl/pfidl_2d/readraw.pro)


    READSTR

    [Previous Routine] [Next Routine] [List of Routines]
    
      Reads a structure dataset into a QS structure array 
      Procedure options are explained below. PFF dataset type must be 
    
      Format: READSTR, STR, [, dataset][, NDSET] [, FILEID = fileid] 
                 [, STRINGLEN = stringlen] [, CLABEL = clabel]
                 [, GRID = GRID] [, PARTICLE = PARTICLE] 
                 [, CONDUCTOR = CONDUCTOR] [, FIELD = FIELD] 
                 [, STRUCTURE = STRUCTURE] [, NO_COPY = no_copy]
      where:
        STR     - QS structure array number
               or an undefined variable - STR will be set to the appropriate
                   structure array number -DELVAR will make a variable undefined
        dataset - indicates a PFF dataset number 
                  or is a search string for dataset comments.  
                  If dataset is missing or zero, then it is set to the 
                  current dataset.
         ndset  - used for conductor data to read more than 1 dataset
            Note: If dataset is a string, a leading `^' indicates that 
                  the string begins at the start of the dataset comment.
        fileid -  file id of the PFF file containing the data
        Clabel -  If CLABEL has a length gt 0, it will be used as the COMMENT label
                  Note: CLABEL = ' ' will result in a blank value for clabel
                        CLABEL = '' will result in the default value
        Particle - Indicates a particle dataset
                   If the Application dataset type is 20, 21, 23 or 24 
                     particle will be set
        Conductor - Indicates a conductor dataset
                    If the Application dataset type is 2, conductor will be set
        Grid     - Indicates a grid dataset
                   If the Application dataset type is 5 or if PFF dataset type 
                   is NG3 (8), grid will be set
        Field    - Indicates a field dataset
                   If the Application dataset type is 11, 12, 13, or 14,
                   Field will be set.
                   Field is the DEFAULT.
        Structure - Structure stored in QS array, STR 
                    Must set no_copy to 0 or -1.
        No_copy   - If keyword is set, structure is returned as undefined
                    Default value = 1
                    If keyword is equal to -1 then only structure is returned
      Examples:
        Read field data in dataset 34 in file id 4 into QS structure array, 5
          readstr, 5, 34, fil=4
        Read next dataset of the current file into QS structure array 6. Assume 
        dataset is particle data.
          readstr, 6, /p (or if QS or TQ data) readstr, 6
        Read next dataset of the current file into QS structure array 7. Assume 
        dataset is particle data and return the sturcture in PAR.
          readstr,7,/p,structure=par (or if QS or TQ data) readstr,7,structure= par
        Read conductor datasets 2, 3, 4, 5 into QS structure array 7.
          readstr, 7, /con, 2, 4 (or if QS or TQ data) readstr, 7, 2, 4
    

    (See ../pfidl/pfidl_2d/readstr.pro)


    REMSD

    [Previous Routine] [Next Routine] [List of Routines]
        Read an image array from an ascii file
        This procedure limited to single block, single vector field data
        WRIMSD will write this ascii format.
    
        format is:  REMSD [, fname] [, STR]  [, /HELPME] 
                            [, Vector_label = vector_label]
        where 
          fname   - the file name
                    If fname = 0 or undefined then dialog_pickfile() will 
                    be used to select a file
          STR     - STR array or STR array number
                    If STR is not provided, then an unused structure array
                    will be used.
          HELPME  - If set, a help statement will be printed.
          Vector_label - If set used as an V1Label in the structure.
    
        Example:
        Read STR array 5 from file 'PFIDLdefault.dat'
           REMSD, 'PFIDLdefault.dat' , 5
    
        Resd STR 3 from a file to be selected from Dialog_Pickfile()
           REMSD , 0, 3
    
        form of file:
          dataset comment
          ndim, lcuniform 
          x axis label 
          y axis label
          z axis label
          nx, ny, nz
          x0, y0, z0 |
          dx, dy, dz |  or x, y, z
          field data
    
      where:
          ndim       = 2 or 3
          lcuniform  = 1 if uniform, 0 if not uniform
      X is uniform if max(dx)-min(dx) is less than 1.22e-4 *max(abs(x))
          axis label = string for axis labels
                       Z label is omitted if ndim = 2
          nx, ny, nz = number of elements in each dimension
                       (NZ omitted if ndim = 2)
          x0, y0, z0 = initial axis values
          dx, dy, dz = axis step size
          x, y, z    = axis values (lcuniform = 0)
                       dz or Z omitted if ndim = 2
          field data = image values
    
       Fortran read:
           integer lu, ndim, lcuniform, nx, ny, nz, i, j, k
           real x(:), y(:), z(:)
           real x0, y0, z0, dx, dy, dz 
           real image( :, :, :)
           character*80 xlabel, ylabel, zlabel, title
     c1     format (a)
           open(file = , unit = lu)
           read(lu, 1) title
           read(lu, *) ndim, lcuniform 
           read(lu, 1) xlabel
           read(lu, 1) ylabel
           nz = 1
           if (ndim .eq. 3) then
             read(lu, 1) zlabel
             read(lu, *) nx, ny, nz
           else
             read(lu, *) nx, ny
           endif 
     c      if fortran 90, allocate x, y, z, image
           if (lcuniform .eq. 0) then
             read(lu, *) (x(i), i = 1, nx)
             read(lu, *) (y(i), i = 1, ny)
             if (ndim .eq. 3) read(lu, *) (z(i), i = 1, nz)
           else
             if (ndim .eq. 2) then
               read(lu, *) x0, y0
               read(lu, *) dx, dy
             else
               read(lu, *), x0, y0, z0
               read(lu, *) dx, dy, dz
             endif
     c        can make x, y, z if desired x(i)= (i-1)*dx + x0, etc.
          endif
          read(lu, *)(((image(i, j, k),i=1,nx),j=1, ny),z=1,nz)
          close (lu)
    

    (See ../pfidl/pfidl_2d/remsd.pro)


    REMSD_EXT

    [Previous Routine] [Next Routine] [List of Routines]
        Read an image array from an ascii file
        This procedure uses only IDL procedures
        This procedure limited to single block, single vector field data
        WRIMSD will write this ascii format.
    
        Format:  REMSD_ext , fname, ARRAY  [, X] [, Y] [, Z]
                 [, DX = dx] [, DY = dy] [, DZ = dz] [, CLABEL = clabel]
                 [, XLABEL = xlabel] [, YLABEL = ylabel] [, ZLABEL = zlabel] 
        where 
          fname   - the file name
                    If fname = 0 or undefined then dialog_pickfile() will 
                    be used to select a file
          ARRAY   - Image array
          X       - X values
          Y       - Y values
          Z       - Z values
          DX      - If uniform data, the point spacing in the X direction
          DY      - If uniform data, the point spacing in the Y direction
          DZ      - If uniform data, the point spacing in the Z direction
          CLABEL  - Comment label
          XLABEL  - X Label
          YLABEL  - Y Label
          ZLABEL  - Z Label
    
        Example:
           Read only the image array from the file 'PFIDLdefault.dat'
           REMSD_ext, 'PFIDLdefault.dat' , image
    
        Read the image from from a file to be selected from Dialog_Pickfile()
           REMSD_ext, 0, image
    
        form of file:
          dataset comment
          ndim, lcuniform 
          x axis label 
          y axis label
          z axis label
          nx, ny, nz
          x0, y0, z0 |
          dx, dy, dz |  or x, y, z
          field data
    
      where:
          ndim       = 2 or 3
          lcuniform  = 1 if uniform, 0 if not uniform
      X is uniform if max(dx)-min(dx) is less than 1.22e-4 *max(abs(x))
          axis label = string for axis labels
                       Z label is omitted if ndim = 2
          nx, ny, nz = number of elements in each dimension
                       (NZ omitted if ndim = 2)
          x0, y0, z0 = initial axis values
          dx, dy, dz = axis step size
          x, y, z    = axis values (lcuniform = 0)
                       dz or Z omitted if ndim = 2
          field data = image values
    
       Fortran read:
           integer lu, ndim, lcuniform, nx, ny, nz, i, j, k
           real x(:), y(:), z(:)
           real x0, y0, z0, dx, dy, dz 
           real image( :, :, :)
           character*80 xlabel, ylabel, zlabel, title
     c1     format (a)
           open(file = , unit = lu)
           read(lu, 1) title
           read(lu, *) ndim, lcuniform 
           read(lu, 1) xlabel
           read(lu, 1) ylabel
           nz = 1
           if (ndim .eq. 3) then
             read(lu, 1) zlabel
             read(lu, *) nx, ny, nz
           else
             read(lu, *) nx, ny
           endif 
     c      if fortran 90, allocate x, y, z, image
           if (lcuniform .eq. 0) then
             read(lu, *) (x(i), i = 1, nx)
             read(lu, *) (y(i), i = 1, ny)
             if (ndim .eq. 3) read(lu, *) (z(i), i = 1, nz)
           else
             if (ndim .eq. 2) then
               read(lu, *) x0, y0
               read(lu, *) dx, dy
             else
               read(lu, *), x0, y0, z0
               read(lu, *) dx, dy, dz
             endif
     c        can make x, y, z if desired x(i)= (i-1)*dx + x0, etc.
          endif
          read(lu, *)(((image(i, j, k),i=1,nx),j=1, ny),z=1,nz)
          close (lu)
    

    (See ../pfidl/pfidl_2d/remsd_ext.pro)


    RM_LINE

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           RM_LINE
    
     PURPOSE:
           Remove a thin verticle line from an image by replacing it with the 
           values in neighboring pixels or by a user specified value.
    
     CATEGORY:
           Image analysis
    
     CALLING SEQUENCE:
    
           RM_LINE, STRUCTURE_in [, STRUCTURE_out]
    
     INPUTS:
           STRUCTURE_in:  Input structure with a vertical line to be removed
              Note:  A copy of STRUCTURE_in is in get_maxstr()
              Note:  This must be a uniform type 1 structure
    
     OPTIONAL INPUTS:
           STRUCTURE_out: Output structure with the vertical line removed
                          If STRUCTURE_out is missing, then output is stored
                          in STRUCTURE_in
              Note:  A copy of STRUCTURE_out is in get_maxstr()-1
    
     KEYWORD PARAMETERS:
          LINEWIDTH: Characteristic width of the line in pixels.
                     Default: LINEWIDTH = 9 pixels
          PLOTIT:  If set, edited image will be plotted.
    
          XCUR:    X-Position of point on the line to be removed.
          YCUR:    Y-Position of point on the line to be removed.
             Note: XCUR and YCUR are always returned with the values used.
                   If no specified on input, ZOOMS is used to determine their value
          PEAK_RATIO: Ratio maximum to minimum value of data that indicates a valid
                      peak 
                      Default: PEAK_RATIO = 1.5
          DERIVATIVE: Ratio of peak derivative to tail value.
                      Values of the derivative below this are considered background.
                      Default: DERIVATIVE  = 0.14  (Minimum value = 0.05)
    
     OUTPUTS:
           Modified image is returned in STURCTURE_out or STRUCTURE_in
           A copy is stored in get_maxstr()-1 
    
     SIDE EFFECTS:
    	Two maximum values of the structure arrays are modified
    
     RESTRICTIONS:
    	Input structure must be a valid type 1 structure with values of
           DX1 and DX2.
    
     PROCEDURE:
           Input image is saved and then smoothed with a width of LINEWIDTH
           The derivative of the smoothed image in the X-direction is taken
              and smoothed with a width of 0.5* LINEWIDTH+1
         The remainder of the operations are performed on each row 
           The center of the line is determined from the smoothed image
           The maximum (MXD) and minimum (MND) derivatives are determined.
           Regions on either side are determined where the derivative is less 
              than DERIVATIVE*MXD and -DERIVATIVE*MND.
           The average values of the original image is linearly propagated 
              across the line
    
     EXAMPLE:
           Eliminate a line from structure 3 and save in structure 4 and plot.
             rm_line, 3, 4, /plot
    
           Eliminate several lines from structure 3 and see the results after 
           each line is removed.  
             rm_line, 3, 3, /plotit
             NOTE: Use the up arrow to remove another line.
                   Use "xfrstr, get_maxstr(), 3" to undo the removal.
    
     MODIFICATION HISTORY:
     	Written by:	L. P. Mix, Jr., November 1, 2006
    

    (See ../pfidl/pfidl_2d/rm_line.pro)


    ROTSTR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
    	ROTSTR
    
     PURPOSE:
    	Rotate, magnify or demagnify, and/or translate an image.
           Based on IDL procedure ROT
       NOTE:  See FLIPSTR for 90 degree rotations and reflections.
           Limited to single block, single vector data (but could be changed.)
           NOTE: Image is interpolated so rather than sequential rotations, 
                 the angles should be summed and one rotation performed.
           Data will be on a uniform rectilinear grid unless exact is set.
           If EXACT is set, data will be finite element type data.
    
     CALLING SEQUENCE:
    	ROTSTR, STR, Angle [, SAVE]  [, EXACT = exact] [, MISSING = missing]
                   [, MAGNIFICATION = magnification] [, CENTER = center]
    		[, GRID = grid] [, INTERPOLATION = interpolation] [, /PIVOT]
    
     INPUTS:
    	STR:	The image array to be rotated.  This is a field type structure
                   or structure array number. It must have two dimensions and be
                   uniform. If it is not uniform, it will be put on a uniform 
                   grid unless EXACT is set.
                   (Array have the same grid spacing in X and in Y.)
                   (Uniform is abs(DX-DY) < 1.5e-5 * range)
           EXACT:  If set rotation will be exact and the result will not be
                   a rectilinear dataset.
                   In exact mode, all rotations are about the point (0, 0)
                   Only ANGLE, SAVE, CENTER and MAGNIFICATION are used for EXACT.
           GRID:   Ignored unless exact is set.
                   If set, puts the data on a uniform rectilinear grid using 
                   the minimum (dx, dy) of the original data.
    	ANGLE:	Angle of rotation in degrees CLOCKWISE. (Why?,
    		because of an error in the old ROT.)
    	SAVE:	Structure array number for the rotated image.
                   If str is a structure array number, then the rotated
                     image will be saved as a structure array number.
                   If str is a structure , then the rotated
                     image will be saved as a structure.
                   Default: If SAVE is missing, rotated image will be returned
                     in STR.
    
    	MAGNIFICATION: Magnification/demagnification factor.
                   A value of 1.0 = no change, > 1 is magnification
                   and < 1 is demagnification.
                   Generally this is not used. Default: magnification =1.0
    
    	CENTER:	(X, Y) Vector Values for the center of rotation.
                   Default: X = 0.5(xmax-xmin)
                            Y = 0.5(ymax-ymin)
                   Note: If PIVOT = 0, then specifying a center is equal to 
                         a translation.
                   Note: PIVOT is ignored if exact is set.
    
    	INTERPOLATION:	Set this keyword for interpolation type. 
                   Default: INTERPOLATION = 1
                   Values:
    		    0  - Nearest neighbor sampling is used.
                       1  - Bilinear interpolation
                       2  - "Cubic convolution" interpolation
                            If this parameter is negative, it specifies the value
                            of the cubic interpolation parameter as described
                            in the INTERPOLATE function.
                            Valid ranges are -1 <= Interp < 0.
                            If INTERP = 2 then INTERP = -1
    
          MISSING:	The data value to substitute for pixels in the output image 
    		that map outside the input image.
                   (See POLY_2D)
    
          PIVOT: Setting this keyword causes the image to pivot around the point
    		X0, Y0, so that this point maps into the same point in the
    		output image.  If this keyword is set to 0, then the
    		point X0, Y0 in the input image is mapped into the center of
    		the output image.
                   Default: PIVOT = 1
    
     OUTPUTS:
    	ROTSTR returns a rotated, magnified, and translated version of the
    	input image.  Note that the dimensions of the output image are
    	always the same as those of the input image.
    
     PROCEDURE:
    	The POLY_2D function is used to translate, scale, and
    	rotate the original image.
    
     EXAMPLE:
    	Rotate the structure 1, 33 degrees and magnify it 1.5 times.
           Use bilinear interpolation to make the image look nice.  Store the 
           result in 1.
    
    		ROTSTR,1, 33, mag =1.5 ; (Bilinear is the default)
      
           Same as above but store the rotated image in 5.
               
    		ROTSTR,1, 33, 5, mag =1.5 ; (Bilinear is the default)
    
           Display an image and determine a horizontal line using LINSTR  
           Rotate the image and make the indicated line horizontal.
           Assume the original image is in 5 and the result to be in 7
                   linstr, 5, slope = slope
                   rotstr, 5, slope, 7
           NOTE:  If multiple rotations are desired it is better to:
                   rotstr, 5, slope1 + slope2, 7
                  The following requires 2 interpolations (avoid if possible):
                   rotstr, 5, slope1, 7
                   rotstr, 7, slope2
    
    	
     MODIFICATION HISTORY:
           Original version: May 6, 1998, lpm
           Using IDL ROT version IDL 5.1 B3
    
    

    (See ../pfidl/pfidl_2d/rotstr.pro)


    RTPSTR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           RTPSTR
    
     PURPOSE:
           Raise field structure components to a power
           Store the result in the initial field structure array or 
             another structure array
           All attribute or vector quantities are raised to a power
     CATEGORY:
           Math 
     CALLING SEQUENCE:
           RTPSTR, STR1, VALUE, [, STR3] [, /EXACT] [, CLABEL = clabel]
     INPUTS:
          STR1:    array number of the first field structure array
          VALUE:   Power to which the first array is raised
     OPTIONAL INPUT:
          STR3:    array number for the result, if not specified the 
                     result is stored in STR1 (the first array)
          EXACT:   If present and not zero, aborts the calculation if STR1 < 0
                     and value is a real.  This is ignored if VALUE is an integer.
          CLABEL:  Optional label for the resultant array
     OUTPUTS:
           NONE    The quotient is stored in a structure array in the common block
     COMMON BLOCKS:
           QSCOM.DAT, QSSTRCOM.DAT
     RESTRICTIONS:
           STR1 array must be defined and have valid data
           VALUE must be defined
     PROCEDURE:
           If  VALUE is an integer then the result is calculated
               Result is STR1^VALUE
               Each attribute, or vector component, of STR1 is raised to the power
    
           If VALUE is not an integer then the result is calculated
               Result is exp(VALUE* alog(STR1)) if STR1 > 0
            or Result is 0.0 if STR1 < 0.0
    
           In either case RESULT is stored in STR3, if specified, or STR1
     EXAMPLES:
           Raise structure 2 to the 1.5 power and store the result in
           structure 3.  Set any negative values in array 2 to zero
                   RTPSTR, 2, 1.5, 3
           Raise structure 2 to the 0.5 power and store the result in 
           structure 3. Do not do the calculation if any values are < 0.0
                   RTPSTR, 2, 0.5, 3, /exact
           Raise structure 2 to the 3 power and store the result back into 2
                   RTPSTR, 2, 3
     MODIFICATION HISTORY:
          Original version, L. P. Mix, August 15, 1993
    

    (See ../pfidl/pfidl_2d/rtpstr.pro)


    S2I

    [Previous Routine] [Next Routine] [List of Routines]
     This function returns a structure from the structure arrays
     Formmat:  s2i, str, i, no_copy = no_copy
       where:  str is the returned structure
               i is the structure number
              no_copy if set, the structure array  will become undefined
    
     Example:
        Obtain sturcture 3 into variable, f1
            s2i, f1,3
    

    (See ../pfidl/pfidl_2d/s2i.pro)


    SCALE_IMAGE

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           Scale_Image
    
     PURPOSE:
           Change the dimensions of an image or single block field dataset.
           Only single block, type 1 (Rectilinear), data is supported.
     CATEGORY: 
           Utility 
     CALLING SEQUENCE: 
           Scale_image, STR, DIM
     INPUTS: 
           STR:      Structure array or Structure Array Number
           DIM:      Dimension(s) to be changed; Must be in the range 1 to NDIM
                     where NDIM is the number of dimensions
    
     KEYWORD PARAMETERS:
       Note: ONE and only ONE of the DIM keywords must be specified.
       Note: POLY in the descriptions below takes an array X and Coefficients C
             and calculates: POLY(X,C)= C[0] + X*C[1] + X*X*C[2] + ... +X^(M)*C[M]
             where M = N_Elements(C)-1
    
           MDIM:     Multiply the current axis values by this coefficient or 
                     array of coefficients.
                     Example: 
                       X is current set of dimensions
                       Xnew = POLY(X, Mdim) is the new set of dimensions
           DDIM:     Calculate the spacing between points by this coefficient or 
                     array of coefficients.
                     Example:
                       X is current set of dimensions
                       Xave is average bin value with one fewer elements.
                       Xave[i]= (X[i]+X[i+1])*0.5
                       dx is the spacing
                       dx[i] = (X[i+1]-X[i])
                       DX = poly(Xave, DDIM)
                       Xnew = [0, total(dx*DX, /cum)
           NDIM:     Calculate the spacing between points by this coefficient or 
                     array of coefficients.  This is similar to DDIM but ignores
                     original position values.
                     Example: 
                       X is current set of dimensions with N values
                       DX = poly(findgen(n-1)+0.5, NDIM)
                       Xnew = [0, total(DX, /cum)
           RDIM:     Reciprocal of the spacing between points is given by this 
                     coefficient or array of coefficients.  
                       X, Xave, dx are the same as in DDIM
                       DX  = POLY(Xave, RDIM)
                       Xnew = [0, total(dx/DX, /cum)
           LABEL:    Replace the DIM axis label with this string.
    
     OUTPUTS:
           NONE:     The specified structure is modified
                   
     COMMON BLOCKS:
           QSCOM, QSSTRCOM 
     RESTRICTIONS:
           STR array must be defined and have valid data
           DIM must be specified
           One of the keywords: Mdim, Ddim, Ndim, or Rdim must be specified.
    
     EXAMPLES:
           Double the value of the points in the y direction on structure 2 and add;            1 to the result.
                Scale_Image, 2, 2, mdim =[1, 2]
    
           Assume an image was made with a magnification of 1.233 and is in
           structure, pict.  Convert the dimensions of the image to the source.
                Scale_Image, pict, [1,2], m=[0,1/1.233], lab = 'Target Dimensions'
    
           Assume a streak camera image in structure 2 with a light burst at 
           4 ns intervals.  Change the Y axis to make it time in ns.
               ; Determine the spacing in the original image and store the 
               ; period in waveform array 66
               get_sweep, 2, 66 
               ; Fit the period and save the coefficients
               wdfit, 66, 67, coef = coef, /plo, degree = 2
               ; Scale the Y axis
               Scale_Image, 2, 2, rdim = coef/4 , lab= 'Time (ns)'
            Note:  A repeat of get sweep should indicate a period of 4 ns.
    
     MODIFICATION HISTORY:
          Original version, L. P. Mix, July 11, 2000
    

    (See ../pfidl/pfidl_2d/scale_image.pro)


    SCALE_REGRID

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           SCALE_REGRID
    
     PURPOSE:
           Fortran routine which will scale data according to a polynomial
           equation with specified coefficients. 
           Note: See also PFF_REGRID 
           Optionally the routine will average points to reduce the size of the
           array.
           Optionally the routine will output the data to a PFF file.
           Note: If fit occurs in the same idl session, then parameters 
                 will be taken from the WDFIT3 common block.
                 READWD3 routine will also fill the WDFIT3 common block.
    
     CALLING SEQUENCE:
          SCALE_REGRID, DATA [, X] [, Y] [, NEWX] [, NEWY]
           [, BREAK = break]  ,C1 = c1 [, C2 = c2] [, C3 = c3] [, FUDGE = fudge]
            [, /EXPONENTIAL] [, /WRITEPFF] [, /REFORM_DATA] [, /ZERO_ORIGIN]
            [, VALID = valid] [, DEFAULT_VAL = default_val]
            [, TLABEL = tlabel] [, CLABEL = clabel]
            [, XLABEL = xlabel] [, YLABEL = ylabel] [, ZLABEL = zlabel]
            [, BLABEL = blabel] [, IER = ier]
     where:
            DATA      - Array to be scaled.  May be one or two dimensions.
                        Data must be a float array.
                        DATA will be be changed.
                        If DATA = DATA (NX, NY) then the returned value will
                        be DATA = DATA (NX/NEWX, NY/NEWY)
                        Note: NY may equal 1
                        If DATA is not 2 dimensional then newy = 1
            X, Y      - Optional X and Y parameters for data.  
                        Two element vector with initial X value and X spacing.
                        Default: X, Y  = [0, 1] 
                        These will be modified dependind on NEWX, NEWY.
            NEWX,NEWY - Used to rescale X or Y 
                        NEWX points in the X direction and NEWY points in the Y
                        direction will be averaged to obtain a new average value.
                        Default: NEWX, NEWY = 1L (No averaging of data)
            ZERO_ORIGIN - If ZERO_ORIGIN is set then X(0)=0.0 and Y(0) = 0.0
                        Otherwise:
                            x(0) = x(0) +x(1)*(newx-1)/2
                            y(0) = y(0) +y(1)*(newy-1)/2
            VALID     - Two element vector with minimum and maximum values for
                        the scaling.  DATA values outside these limits will be
                        set to the values of default.
                        Default: VALID = [min(data, max = mdata), mdata]
            DEFAULT_VAL- If DATA is outside the range set by valid, then these are
                        the values to which DATA will be set.
                           If data < valid(0) then data = default_val(0)
                           If data > valid(1) then data = default_val(1)
                        Default values are: DEFAULT_VAL = scale_regrid(VALID)
                           unless EXPONENTIAL is set.
                        If exponential is set, DEFAULT_VAL(0) = 0.0
            BREAK     - A vector of one or two elements indicating the positions
                        where the C1 coefficients go to the C2 coefficients.
                        The second element, if it exists, is where the C2
                        coefficients go to the C3 coefficients.
                        For three regions to the fit, C1, C2 and C3 must each have 
                        two or more elements and BREAK must have two elements.
            FUDGE     - Factor used to insure the function is continuous between
                        polynomial fits. Ignored if N_Elements(c2) lt 2
                        This is, if data has no breaks fudge is not used.
                        Default: FUDGE = 0.05 of Valid 
                        Fudge details:
                        Segment 1, 2 and 3 (if there are 2 break points) are
                        modified according to the following:
                        Let x be the value of image and y the scaled value.
                          y = poly( x, c1)
                          range1 = break(1)-valid(1)
                        if (break(1)-x)/range1 is less than fudge/2 then y is
                         modified
                          y = y+delta1 *(1-(break(1)-x)/(fudge*range1))
                        where delta1= poly(break(1), c2)-poly(break(1),c1)
                        C2 is also modified.
           Exponential- If set then after the scaling the data will be exponentiated.
                        Default: Exponential = 0
                        If exponential = 0 then data = poly(data, C)
                        If exponential = 1 then data = exp(poly(data, C))
            WRITEPFF  - If set, data will be written to the current PFF file.
                        Default: WRITEPFF = 0
           REFORM_DATA- If set, data will be reformatted to:
                           data = data;   if newx = 1, newy = 1
                     else  data = data(nx/newx, ny/newy)
                        Default: If WRITEPFF is set, data will not be reformatted.
                                 If WRITEPFF is not set, data will be reformatted.
          The following are used only if WRITEPFF is set
            Default value for all these is: '  '
            TLABEL    - Dataset TYPE label
            CLABEL    - Dataset COMMENT label
            XLABEL    - Dataset X label
            YLABEL    - Dataset Y label
            ZLABEL    - Dataset Z label
            BLABEL    - Dataset BLOCK label
                        
     EXAMPLE:
           Obtain polynomial scaling of the form:
              y = 45 + 7x + 3x^2 
           for 501 x values in the range 0 to 10 and plot the results.
              image = findgen(501)*(10.0/500)
              xx = image ; need to save a copy for the plot
              SCALE_REGRID, image,c1=[45, 7, 3]
              plot, xx, image
    
     MODIFICATION HISTORY:
     	Written by:	Paul Mix, August 3, 1998
    

    (See ../pfidl/pfidl_2d/scale_regrid.pro)


    SCANF

    [Previous Routine] [Next Routine] [List of Routines]
     PURPOSE:
           Use XINTERANIMATE to build an animation of a DO-list of 
           datasets of FIELD snapshots
     CALLING SEQUENCE:
           ScanF, FLD, NORM, NORM_VAL, Start [, Stop] [, Skip]
                   [, CON=CON] [, SCALE=SCALE ] [, INDEX=INDEX ]
                   [, XSIZE = xsize] [, YSIZE = ysize] [, Block = block]
                   [, WINNUM=WINNUM ] [, _EXTRA = EXTRASTUFF]
     INPUTS:
           FLD :     Field component
           NORM:     Plane normal for PLOTFLD
           NORM_VAL: Value of normal ordinate (PLOTFLD argument)
           Start \  
           Stop -  DO list for frames in file.
           Skip  /  
           Default Value for Stop is number of datasets in current PFF file
           If Stop le start then stop = ndspff()
           If Skip le 0 or undefined then skip = 1
     OPTIONAL INPUT:
           -none-
     KEYWORDS:
           CON:    Conductor structure
           SCALE:  Scale factor for field (QHRE argument)
           INDEX:  Index of plane (PLOTFLD option)
           WINNUM: IDL window number
           XSIZE:  X Size of the window; Default = 448 (7*64)
           YSIZE:  Y Size of the window; Default = 384 (6*64)
           BLOCK   Xinteranimate called with block = block
    
     Example
           Make a movie using datasets 215 to 228, with levels from 0 to 
              8e8 and put a thermometer on the plot in the theta plane at 
              theta = 0.  Plot the square root of the sum of the squares
              of the vector components.
          ScanF, [1,2,3], 2, 0, 215,  228, 1,lev=[0, 8e8], /ther
    

    (See ../pfidl/pfidl_2d/scanf.pro)


    SCANGRD

    [Previous Routine] [Next Routine] [List of Routines]
     PURPOSE:
           Use XINTERANIMATE to build an animation of a DO-list of slices of 
            a GRID or CONDUCTOR snapshot
     CALLING SEQUENCE:
           ScanGRD, STR,  NORM, Start [, Stop] [, Skip]
                   [, CON=CON]  [, INDEX=INDEX ] [, VALUES = values]
                   [, XSIZE = xsize] [, YSIZE = ysize]
                   [, WINNUM=WINNUM ] [, _EXTRA = EXTRASTUFF]
     INPUTS:
           STR :     Structure array value or field structure
           NORM:     Plane normal for PLOTGRD
           Start \  
           Stop -  DO list for frames in the normal direction.
           Skip  /  
           Default Value for Stop is number of Number of planes in Normal direction
           If Stop le start then stop = number of indices in NORM direction
           If keyword_set(index) then 
           If Skip le 0 or undefined then skip = 1
            
     OPTIONAL INPUT:
           -none-
     KEYWORDS:
           CON:    Conductor structure
           VALUES: If present then START, STOP and SKIP are ignored.
                     VALUES is an array of normal values.
           SCALE:  Scale factor for field (QHRE argument)
           INDEX:  Index of plane (PLOTFLD option), Default =1
                   If index eq 0 then default then skip must be defined.
           WINNUM: IDL window number
           XSIZE:  X Size of the window; Default = 448
           YSIZE:  Y Size of the window; Default = 384
    
     Example
           Make a movie using structure array 4 starting at -.1 to 1.1 in 
             increments of .05. Use array 5 to overlay the conductors.
             Make the z axis as the normal direction and show theta as a polar plot
            ScanGRD,4,3, -.1, 1.1, 0.01, con =5, /polar
     
           Make a movie of structure 5 with a normal direction of 3 at values of
              Z given by gz.  Overlay a conductor from structure 2
            SCANGRD, 5, 3, values = gz, con= 2 
    
           Make a movie of the conductors in structure 2 reflected about theta=0
           Use the z values from block 1.
            image, 2, 3, ref = -2
            scangrd, 3, 3, val = get_array(2, 1, 1), /polar 
           
             
    

    (See ../pfidl/pfidl_2d/scangrd.pro)


    SCANP

    [Previous Routine] [Next Routine] [List of Routines]
     PURPOSE:
           Use XINTERANIMATE to build an animation of a DO-list of 
           datasets of FIELD snapshots
     CALLING SEQUENCE:
           ScanP, Xaxis, Yaxis, Weight, Start [, Stop] [, Skip]
                   [, CON=CON] [, SCALE=SCALE ] [, INDEX=INDEX ]'
                   [, XSIZE = xsize] [, YSIZE = ysize]
                   [, WINNUM=WINNUM ] [, _EXTRA = EXTRASTUFF]
     INPUTS:
           Xaxis :  Particle parameter for the horizontal axis
           Ysxis :  Particle parameter for the vertical axis
           Weight : Value of normal ordinate (PLOTFLD argument)
           Start \  
           Stop -  DO list for frames in file.
           Skip  /  
           Default Value for Stop is number of datasets in current PFF file
           If Stop le start then stop = ndspff()
           If Skip le 0 or undefined then skip = 1
     OPTIONAL INPUT:
           -none-
     KEYWORDS:
           CON:    Conductor structure
           INDEX:  Index of plane (PLOTFLD option)
           WINNUM: IDL window number
           XSIZE:  X Size of the window; Default = 448
           YSIZE:  Y Size of the window; Default = 384
    
     Example
           Make a movie using datasets 215 to 228, with axis 3, 1, and 
              color each particle using charge as weight
          ScanP, 3, 1, -4,  215,  228, 1
    

    (See ../pfidl/pfidl_2d/scanp.pro)


    SCANS

    [Previous Routine] [Next Routine] [List of Routines]
     PURPOSE:
           Use XINTERANIMATE to build an animation of a DO-list of slices of 
            a FIELD snapshot
     CALLING SEQUENCE:
           ScanS, STR, FLD, NORM,  Start [, Stop] [, Skip]
                   [, CON=CON] [, SCALE=SCALE ] [, INDEX=INDEX ]'
                   [, XSIZE = xsize] [, YSIZE = ysize]
                   [, WINNUM=WINNUM ] [, _EXTRA = EXTRASTUFF]
     INPUTS:
           STR :     Structure array value or field structure
           FLD :     Field component
           NORM:     Plane normal for PLOTFLD
           Start \  
           Stop -  DO list for frames in the normal direction.
           Skip  /  
           Default Value for Stop is number of datasets in current PFF file
           If Stop le start then stop = number of indices in NORM direction
           If Skip le 0 or undefined then skip = 1
     OPTIONAL INPUT:
           -none-
     KEYWORDS:
           CON:    Conductor structure
           SCALE:  Scale factor for field (QHRE argument)
           INDEX:  Index of plane (PLOTFLD option), Default =1
                   If index eq 0 then default then skip must be defined.
           WINNUM: IDL window number
           XSIZE:  X Size of the window; Default = 448
           YSIZE:  Y Size of the window; Default = 384
    
     Example
           Make a movie using structure array 4 with every other plane
              and put a thermometer on the plot and use theta as the slice plane
              Plot the square root of the sum of the squares
              of the vector components. Scale the field between 0 and 8e8
          ScanS,4,  [1,2,3],2,1,0,2,lev=[0, 8e8], /ther
    

    (See ../pfidl/pfidl_2d/scans.pro)


    SCANV

    [Previous Routine] [Next Routine] [List of Routines]
     PURPOSE:
           Use XINTERANIMATE to build an animation of a DO-list of 
           datasets of FIELD snapshots
     CALLING SEQUENCE:
           ScanF, FLD, NORM, NORM_VAL, Start [, Stop] [, Skip]
                   [, CON=CON] [, INDEX=INDEX ]'
                   [, XSIZE = xsize] [, YSIZE = ysize] [, WORK = work]
                   [, WINNUM=WINNUM ] [, _EXTRA = EXTRASTUFF]
     INPUTS:
           FLD :     Field components for the vector plot
                     Must have two or more elements
                     If 0 or undefined, value = [1,2]
           NORM:     Plane normal for PLOTFLD
           NORM_VAL: Value of normal ordinate (PLOTFLD argument)
           Start \  
           Stop -  DO list for frames in file.
           Skip  /  
           Default Value for Stop is number of datasets in current PFF file
           If Stop le start then stop = ndspff()
           If Skip le 0 or undefined then skip = 1
     OPTIONAL INPUT:
           -none-
     KEYWORDS:
           CON:    Conductor structure
           INDEX:  Index of plane (PLOTFLD option)
           WINNUM: IDL window number
           WORK  : One or two element vector used to calculate the components.
                   If only one element then work= [work, work+1]
                   Default values are [maxstructure-4, maxstructure-3]
           XSIZE:  X Size of the window; Default = 448
           YSIZE:  Y Size of the window; Default = 384
         _EXTRA :  Valid keyword for PLOTVEC
     
     Example
           Make a movie using datasets 215 to 228, with levels from 0 to 
              8e8 and put a thermometer on the plot in the theta plane at 
              theta = 0. 
          ScanV, [3, 1], 2, 0, 215,  228, 1,zrange=[0, 8e8], /ther
    

    (See ../pfidl/pfidl_2d/scanv.pro)


    SET_MAXSTRARRAY

    [Previous Routine] [Next Routine] [List of Routines]
        Set the maximum number of structure arrays
    
        format:
            set_maxstrarray, maxstr [, /quiet]
            where
              maxstr - an integer indicating the maximum number of structure arrays
                       maxstr = abs(long(maxstr)) > 10
                       Default maximum is 82
    
              QUIET  - If set no warning will be issued if the number of
                       datasets is decreased
    
             Note: If the number of structure arrays is decreased, data can be lost.
                   Any data above maxstr will be deleted.
    
        Example:
            Set the number of structure arrays to 102.
               set_maxstrarray, 102
    

    (See ../pfidl/pfidl_2d/set_maxstrarray.pro)


    SHELP

    [Previous Routine] [Next Routine] [List of Routines]
    
     NAME:
          SHELP
     PURPOSE:
          Show the elements of a QS structure or show the structures 
            in the qs common area
     CALLING SEQUENCE:
          SHELP  [, SMIN] [, SMAX] [, /FULL] [, /IDLHELP]
     INPUTS:
          SMIN   - First sturcture array number to be listed or an array of 
                   structure array numbers or a QS structure
             or
                 If a single parameter, SMIN can be a search string.
                 Those arrays containing the string in the dataset comment will
                   be listed. The full set of wild card options is available.
                   See GET_MATCH
           Note: FULL = 0 if SMIN is a string
          SMAX   - Last structure array number
          FULL   - If present and not zero, the full structure array
                   information is printed.  If full is zero, only the dataset
                   comment is printed
                   Default:
                   SMIN and SMAX are missing, then FULL = 0
                   SMAX is missing, then FULL = 1
                   Otherwise, FULL = 0
          IDLHELP- If present and not zero, the structure component information
                   provided by "help, /structure" is provided. Default is 
                   IDLHELP =0
          Comment- If set, full comment will be printed. ';' or ';;'will be taken as a
                   carriage return. If comment is set, then full = 0.
             Note: If one instance of ';;' is found that will be the delimiter
                   for the remainder of the line.
    
     Outputs:
          Structure parameters
     Example:
          See the contents of all structure arrays
             shelp
          See the full contents of structure, f12
             shelp, f12
          See the dataset comment only of structure array, f12
             shelp, f12, full= 0
          See the full contents of structure arrays 1 through 3
             shelp, 1, 3, /full
     (or)    shelp, [1,2,3]
          See the contents of structure arrays 10 through 20
             shelp, 10, 20
    

    (See ../pfidl/pfidl_2d/shelp.pro)


    SLICE

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
    	SLICE
    
     PURPOSE:
    	Reduce a three or four dimensional field structure to two dimensions
           Note: Four dimensional data is checked for valid data as closely as 3D
           data.
    
     CATEGORY:
    	Graphics
    
     CALLING SEQUENCE:
    
    	Structure2 = SLICE (Structure1, Field, Kvalue1, Value1, Kvalue2, Value2)
    
    
     INPUTS:
    	Structure1: Input this is a multidimensional field type structure.
                         or a structure array numbger
           Structure2: Output this is a two dimensional field structure or 
                         a multidimensional field structure with degenerate
                         dimensions.
           Field:      Field component to be sliced
           Note: Field may be positive or negative; Field = -(abs(Field))
           Note: If Field is an array, the square root of the sum of
                 the squares will be used.
           Note: If A has only one attribute (such as an image or a charge density);
                 the this parameter can be omitted.
           KVALUE1,2
                 If Field is a two dimensional field then these values are ignored.
                 If Field is a three or four dimensional field then these values
                   indicate the coordinates which are fixed for the two
                   dimensional plots.
           VALUE1, 2
                 If Field is a two dimensional field then these values are ignored
                 If Field is a three or four dimensional field then these values
                   indicate the coordinate values for the fixed dimensions in
                   the two dimensional plots. Linear interpolation is used
                   according to the value of VALUE1. If VALUE1 has two elements
                   the average value over the interval is used.
                 WARNING: If INDEX is specified, VALUE1 will be changed to spatial
                          coordinates using the midpoints of the bins.
    
     KEYWORDS:
           INTEGRATE If present and not zero, integrate the slice.
                     The integral will be performed between value1(0) and value1(1)
                     If integrate = 1, a simple integral
                     If integrate = 2, a x dx integral
                     If integrate = 3, a x^2 dx integral
                     Limitations:
                         Data must have a single block
                         Two values of value 1 must exist
           OVERPLOT: If overplot is not zero and kvalue1,2 is undefined, the 
                     values will be taken from the last plot.
           BLOCK   : If the field is multi-block, BLOCK can be used to specify
                     one or more blocks to be sliced.  BLOCK is an array of one
                     or more values.
           INDEX   : If present and not zero, then the units of VALUEi will be
                     taken as indices of of the field array.  Valid values are
                     1 to the maximum number of values in KVALUEi.
                     Care should be exercised with multiple block data.
                 WARNING: If INDEX is specified, VALUE1 will be changed to spatial
                          coordinates using the midpoints of the bins.
           VECTOR  : If set all vector components will be returned.
    
     OUTPUTS:
    	Structure is modified to produce a two dimensional structure or 
           a structure with n-dimensions and all but two degenerate
    
     EXAMPLE:
    	Reduce structure f to a two dimensional structure by slicing along
             the second dimension between 0.0 and 0.4 Save the magnitude of the
             field vector in structure g.
           g = SLICE (f, [1,2,3], 2, [0.0, 0.4])
    
           Assume d is a charge density structure with one attribute.  Take a slice 
             at z= 0.25 and store in sturcture array 12.
           i2s, SLICE (d, 3, .25), 12
       i2s, SLICE(d, 1, 3, .25), 12
    
     MODIFICATION HISTORY:
     	Written by:	Paul Mix, August 10, 1993
    

    (See ../pfidl/pfidl_2d/slice.pro)


    SLICEALL

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
    	SLICEALL
    
     PURPOSE:
    	Reduce a multi-dimensional field structure to fewer dimensions
           Up to 6 dimensions are supported.
           Output array must be less than 4 dimensions
           Only single block, type 1 structures are supported.
    
     CATEGORY:
    	Graphics
    
     CALLING SEQUENCE:
    
    	Structure2 = SLICEALL (STRUCTURE1, DIMENSION, VALUE, /INDEX, WDF = wdf)
    
     INPUTS:
    	STRUCTURE1: Input this is a multidimensional field type structure.
                         or a structure array numbger
           Structure2: Output this is a Multi-dimensional field structure or 
                       a wdf array number if Structure 1 is reduced to one dimension.
                       The reduced structure has knowledge of the eliminated
                       dimensions only through the dataset comment.
                       All field components are sliced.
                       If a one-dimensional data structure remains, it will be stored
                       in a WDF array.  The array numbers are returned in STRUCTURE 2.
                       If not specified, the arrays are stored in 
                       (get_maxwdf()-nvect) and successive arrays.
           DIMENSION:  A dimension or an array of dimensions to be removed.
                       The dimensions are numbered from 1 to the total number of
                       dimensions.
           VALUE:      A value or an array of values for each dimension.
                       This value will be changed to the nearest bin value.
              WARNING: If INDEX is specified, VALUE will be changed to spatial
                       coordinates of the bin.
    
     KEYWORDS:
           INDEX:      If present and not zero, then the units of VALUE will be
                       taken as indices of of the spatial array.  Valid values are
                       1 to the maximum number of values in in that dimension.
              WARNING: If INDEX is specified, VALUE will be changed to spatial
                       coordinates of the bin.
                     
           VECTOR:     If set all vector components will be returned.
           WDF:        WDF array number to store the one dimensional arrays.  Ignored
                       if the number of DIMENSIONS + 1 is not equal to the number of 
                       spatial dimensions in STRUCTURE1.
     METHOD:  
           Dimensions are removed to produce a field with reduced dimensions.
           For example if the field of structure 1 is F1[3, 4, 6, 7, 8, 9]
           and dimension = [2, 3, 5] the new field will have dimension 
           F2[3, 7, 9] and the values of the missing dimensions will be stored
           in the dataset comment only.
    
           The index value is determined using the MIN function to determine the cut plane.
              If X is the array of values for the dimension and VALUE is the desired value, 
              the array is cut along the index K given by:
                junk = min(X - Value, /absolute, K)
              If INDEX is set, then K = VALUE-1 (since IDL uses a zero initial offset)
    
     EXAMPLE:
    	Reduce structure 4 (a 3D structure) a two dimensional structure by 
           slicing along the second dimension at 0.4.
           Save the sliced structure in g.
             g = SLICEALL (4, 2, 0.4)
    
           Save a line out of the 3D structure p in wdf array 8 at y = 4 and z = .4
             w = sliceall(p, [2, 3], [4, .4], wdf = 8)
    
     MODIFICATION HISTORY:
     	Written by:	Paul Mix, October 25, 2005.
    

    (See ../pfidl/pfidl_2d/sliceall.pro)


    SMOSTR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           SMOSTR
    
     PURPOSE:
           Smooth the Vectors of a Type 1 field structure
    
     CATEGORY: 
           Utility 
    
     CALLING SEQUENCE: 
           SMOSTR, STR_IN [, STR_OUT] 
     INPUTS: 
           STR_IN:   Structure array number or structure array to be smoothed.
                     If STR_OUT is specified, then STR_OUT = SMOOTH(STR_IN)
           STR_OUT:  Structure array number or structure array for the smoothed 
                     result.  If STR_OUT not is specified, then 
                     STR_OUT = SMOOTH(STR_IN)
     KEYWORD PARAMETERS:
           MEDIAN:   If set a median filter is used using the IDL routine MEDIAN.
                     Default is boxcar filter using the IDL routine SMOOTH.
           WIDTH:    Width of the filter.  Default = 3
                     If width is greater than array dimensions, then no action is 
                     taken.
           XONLY:    If set, smooth only in the X direction, one row at a time.
                     Limited to 2 dimensional data
           YONLY:    If set, smooth only in the Y direction, one column at a time.
                     Limited to 2 dimensional data
           _EXTRA:   Any valid keyword for MEDIAN or SMOOTH.
           
     OUTPUTS:
           The specified structure is filtered and returned in STR_IN or STR_OUT
    
     RESTRICTIONS:
           STR_IN array must be defined and have valid data.
            NOTE:  Results with multi block data may not be satisfactory 
                   along block boundaries.
    
     TECHNIQUE:
           IDL procedures SMOOTH and MEDIAN are used to filter each block of a 
           type 1 field structure.  Loops are used.
    
     EXAMPLES:
           Smooth structure 2 with a boxcar filter.
                SMOSTR, 2
           Smooth structure 2 with a boxcar filter of width 7 and store the result
             in structure 3.
                SMOSTR, 2, 3, width = 7
           Smooth structure 2 with a boxcar filter of width 7 and store the result
             in structure 3. Use Edge Truncation.
                SMOSTR, 2, 3, width = 7, /edge
           Smooth structure 2 with a median filter of width 7 and store the result
             in structure 3.
                SMOSTR, 2, 3, width = 7, /median
           Smooth structure density a median filter of width 3 and store the result
             in structure smodensity.
                SMOSTR, density, smodensity, /median
           Smooth structure 2 with a median filter of width 40 in the Y direction
           Smooth the result with a median filter of width 3 in both directions
           Store the result in structure 3.
                SMOSTR, 2, 3, width = 40, /yonly, /median
                SMOSTR, 3, /med
           
     MODIFICATION HISTORY:
          Original version, L. P. Mix, September 18, 2001
    

    (See ../pfidl/pfidl_2d/smostr.pro)


    SOLID

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           SOLID
     PURPOSE:
           This procedure loads datasets from a PFF geometry file and
           uses PFIDL's solid modeling tools to render a 3D display.
           The model is stored for future reference and can be retrieved
    
           See also "PLOTCON, SOLID_MODEL = omodel" ; omodel ne 0
    
     CATEGORY:
           Solid modeling
    
     CALLING SEQUENCE:
           SOLID [, FILE]
     or    SOLID , START [, NCON]
    
     INPUTS:
           File: File name
            If file name = 0, dialog_pickfile is called.
            Default: FILE = 'qsgeo.pff'
                     If no file called 'qsgeo.pff' is present,
                       DIALOG_PICKFILE is called.
           Note:  SKIP, NODIEL, INCLUDE keywords apply only to FILE input
           or
           START : Array of structure array numbers for the conductors
                   or Initial structure array value
           NCON  : Number of structure arrays
                   NOTE:  NCON is ignored for START is an array
                   Default: NCON = 1
           Note:   SKIP, NODIEL, INCLUDE keywords do not apply to specified structures
    
     KEYWORDS PARAMETERS:
           AXIS_ADD: If set, an axis will be added to the 3D model
                     If AXIS_ADD is a structure, it will be
                      passed to ADD_AXIS as an _EXTRA keyword.
           BLOCK:    If set, the solid model is displayed in a blocking widget
                     If undefined, then BLOCK defined by the following:
                           DEFSYSV, "!callable_idl", exists = BLOCK
           NODIEL:   Do not render dielectric objects (vacuum is always skipped)
           INCLUDE:  Datasets to include.
                     Default is datasets 3 to the last dataset
           SKIP:     Dataset name or number to skip
                     If skip is a string, it will be used as a search string.
           COLOR:    Array of colors for the objects
           BCOLOR:   Array of colors for the rear of the objects
                     Default:  BCOLOR = COLOR
           FINTENSITY: Foreground color intensity for each object
                Note:  FINTENSITY may be a scalar or an RGB triplet
                       Default:  FINTENSITY = 1.0
           BINTENSITY: Background color intensity for each object
                       Default:  BINTENSITY = 0.6
           TRANS:    Transparency flag for the objects (0 = off, 1 = on)
           MODEL:    If present, the model is returned
           RETRIEVE: If set, no pff file will be opened and the last model
                     returned in MODEL
           SPAWN:    If set, spawn to another IDL process
    
     TECHNIQUE:
           Solid model is generated and returned in the MODEL keyword.
           Two models will be stored in a common block
           After two models are stored, additional calls to SOLID will result
           in the destruction of the first solid model, the second model will
           be moved to the first model location and the current model will be
           stored.
           The current model can be retrieved with the RETRIEVE keyword.
    
     Examples:
           Make a solid model of datasets 3, 4, 6 in the qsgeo.pff file in the
             current directory.
             SOLID, include=[3, 4, 6]
    
           Make a solid model of structure array numbers: 3, 4, 5.
             SOLID, [3, 4, 5]
     or      SOLID, 3, 3
    
     MODIFICATION HISTORY:
           Original version, M. F. Pasik, April 3, 2000
           Added color options, TDP, 02/14/02
           Added common block to save the model, LPM, 06/18/04
           Added routine to PFIDL_2D, LPM, 06/18/04
    

    (See ../pfidl/pfidl_2d/solid.pro)


    SPEC

    [Previous Routine] [Next Routine] [List of Routines]
      Procedure SPEC
      This procedure produces the energy values and time of flights for a
      magnetic spectrometer.  The geometry assumes a planar anode on the left.
      Next a planar gas cell with a three element scattering foil in the center.
      Gas pressure and type may be different on either side of the scatterer.
      The spectrometer is assumed to be at an angle to the direct beam and to 
      have one foil at its entrance. The magnetic field in the magnet is assumed
      constant over the diameter.
      
      format: SPEC, fileout, filein, quiet= quiet, length = length
        where: 
        fileout  - Name of file with the output
        filein   - Input file with spectrometer values
        length   - length of trajectory in the magnetic field
        quiet    - Range information will be printed if quiet is 0
     Note: if the ion charge is greater than z or less than 0  then 
           all possible charge states will be calculated.
           
                   Default: QUIET=1
      
      Example:
                spec
    

    (See ../pfidl/pfidl_2d/spec.pro)


    SPLIT_COLORS

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           SPLIT_COLORS
    
     PURPOSE:
           Find the minimum and maximum of a vector and build a compound color
           table for positive and negative values.
    
     CATEGORY:
           Graphics
    
     CALLING SEQUENCE:
           Split_Colors, Structure, Vector, BOTTOM = bottom, TOP = top, 
                         LEVELS = levels, _extra = extrastuff
    
     INPUTS:
           Structure - Structure array number or idl field Structure.
       or  LEVELS    - Minimum and maximum for the compound color table.
    
     OPTIONAL INPUTS:
           Vector    - Vector component desired if Structure contains more than
                       one vector
           Bottom    - Color table value used for values below zero
                       Default = 7
           Top       - Color table value used for values above zero
                       Default = 1
           File      - File where colors are stored (see LOADCT)
    	
     EXTRA KEYWORD PARAMETERS (Sent to MINSTR):
           XRANGE    - Range of the first dimension for the minimum search.
                       Default:  All X values
           YRANGE    - Range of the second dimension for the minimum search.
                       Default:  All Y values
           ZRANGE    - Range of the third dimension for the minimum search.
                       Default:  All Z values
           LOCATION  - Position where minimum occurs
           PMINIMUM  - Same as LOCATION
           MAXIMUM   - Maximum val in the range defined.
           PMAXIMUM  - Position where MAXIMUM occurs.
    
     OUTPUTS:
           The split color table is loaded
    
     OPTIONAL OUTPUTS:
           If levels is undefined or a scalar, the minimum and maximum values are
             returned.
    
     EXAMPLE:
           Load a split color table for the electric field structure E
             split_colors, e
    
           Load a split color table for the Z component of the field in structure 4
           Return the min and max in lev.
             split_colors, 4, 3, lev = lev
    
           Load a split color table for a range of [-100, 200]
             Use color table 7 for the negative values and 1 for the top values
             split_colors,  lev = [-100, 200], b=7, t =1
    
     MODIFICATION HISTORY:
           Written by:     L. P. Mix, June 20, 2000
    

    (See ../pfidl/pfidl_2d/split_colors.pro)


    STACK_XYZ

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           STACK_XYZ
    
     PURPOSE:
           Put a series of Structures together in the X, Y, or Z direction.
    
     CALLING SEQUENCE:
    
           STACK_XYZ, STRARRAY, NSTR, PAD = pad, WIDTH = WIDTH, OUT = OUT
             XAXIS = xaxis, YAXIS = yaxis, ZAXIS = zaxis
    
     INPUTS:
           STRARRAY - Structure array number, array of structure array numbers, 
                       or string matching a structure comment 
           NSTR     - If STRARRAY is a single value, then that value and the 
                      next (NSTR -1) values will be used.
    
     KEYWORD PARAMETERS:
    
           PAD      - Fraction used to pad between images.
                      This number with typically be ~0.01 for most applications.
                      The space will be PAD * width of the added image.
           WIDTH    - X, Y, or Z increment to use between all images.
                      If pad is not specified and width is not specified, then
                      width = 0.01* width of the first image.
           OUT      - Output structure array number.
                      Default is (get_maxstr()-1)
           XAXIS    - Stack along the X axis (This is not checked.)
           YAXIS    - Stack along the Y axis
           ZAXIS    - Stack along the Z axis
             NOTE:  If no axis is specified, then XAXIS =1
                    actual code:
                    if keyword_set(zaxis) then stack_axis =3 else $
                      if keyword_set(yaxis) then stack_axis =2 else stack_axis = 1
     OUTPUTS:
           The resulting composite sturcture will be returned.
    
     RESTRICTIONS:
           Only structures supported by "JOINSTR" can be combined.
           The maximum structure is used as a work array.
    
     PROCEDURE:
           In the direction of stacking, coordinate will be will be modified to 
           be adjacent to the previous structure with a user specified gap.
           The procedure puts different structures in different blocks.  This 
           allows the exact coordinates to be maintained.
    
     EXAMPLE:
           Combine structures 22, 23 in the x direction and store the result in 30
             STACK_XYZ, 22, 2, out =30
        or
             STACK_XYZ, [22, 23] , out =30
    
     MODIFICATION HISTORY:
     	Written by:	L. P. Mix, April 24, 2002
    

    (See ../pfidl/pfidl_2d/stack_xyz.pro)


    STRCOMMENT

    [Previous Routine] [Next Routine] [List of Routines]
      This function returns the structure comment for an array. 
      Format:  com = STRCOMMENT(STR)
      where:
        STR - Valid Structure number or PFIDL structure
      Example:
        Print the comment label for structure array 5
          Print, strcomment(5)
        Add the shot number to a comment of structure array 3, 
           where shot number is SHOT.
          chastr, 3, c= strcomment(3)+', Shot '+strtrim(shot, 2)
    
    

    (See ../pfidl/pfidl_2d/strcomment.pro)


    STRINFO

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           STRINFO
    
     PURPOSE:
           This procedure returns the parameters for a structure
           This is similar if not identical to STRLIMITS
    
     CALLING SEQUENCE:
           STRINFO, STR [, TYPE = type] [, FILE = file] [, NDIM = ndim]
                [, CLABEL = clabel] [, TLABEL= tlabel]
                [, XRANGE = xrange] [, YRANGE = yrange] [, ZRANGE = zrange] 
                [, TRANGE = trange] [, RANGE = range]
                [, NBLOCK = nblock] [, NATTR = nattr]
                [, DX = dx] [, DY = dy] [, DZ = dz] [, DT = dt]
                [, V1 = v1] [, V2 = v2] [, V3 = v3] [, V4 = v4]
                [, V5 = v5] [, V6 = v6] [, V7 = v7] [, V8 = v8]
                [, AV1 = av1] [, AV2 = av2] [, AV3 = av3] [, AV4 = av4]
                [, AV5 = av5] [, AV6 = av6] [, AV7 = av7] [, AV8 = av8]
    
     INPUTS:
           STR:    Valid structure number, PFIDL structure, or search string 
                   for the structure comment
    	
     KEYWORD PARAMETERS:
           Note: Default values are 0 except for CLABEL
           TYPE:   Structure type 
           FILE:   File name for the data
           NDIM:   Number of dimensions
           CLABEL: Structure Comment Label
           TLABEL: Structure Type Label
           XRANGE:	Range of X-values, or first dimension
           YRANGE:	Range of Y-values, or seconc dimension
           ZRANGE:	Range of Z-values, or third dimension
           TRANGE: Range of T-values, or fourth dimension
           RANGE:  Structure RANGE variable with spatial ranges by block
           NBLOCK: Number of blocks
           NATTR:  Number of attributes or vector components
           DX:     DX for first dimension, ZERO if non-uniform or unknown
           DY:     DY for second dimension, ZERO if non-uniform or unknown
           DZ:     DZ for third dimension, ZERO if non-uniform or unknown
           DT:     DT for fourth dimension, ZERO if non-uniform or unknown
           V1:     Range of first vector component or attribute
           V2:     Range of second vector component or attribute
           V3:     Range of third vector component or attribute
           V4:     Range of fourth vector component or attribute
           V5:     Range of fifth vector component or attribute
           V6:     Range of sixth vector component or attribute
           V7:     Range of seventh vector component or attribute
           V8:     Range of eighth vector component or attribute
           AV1:    Average and Standard Deviation 
                   of first vector component or attribute
           AV2:    Average and Standard Deviation 
                   of second vector component or attribute
           AV3:    Average and Standard Deviation 
                   of third vector component or attribute
           AV4:    Average and Standard Deviation 
                   of fourth vector component or attribute
           AV5:    Average and Standard Deviation 
                   of fifth vector component or attribute
           AV6:    Average and Standard Deviation 
                   of sixth vector component or attribute
           AV7:    Average and Standard Deviation 
                   of seventh vector component or attribute
           AV8:    Average and Standard Deviation 
                   of eighth vector component or attribute
    
     OUTPUTS:
           Specified keyword parmeters are returned
    
     PROCEDURE:
           The specified structure is retrieved and the keyword parameters are 
           extracted.  The average and standard deviation are calculated 
             Average = Total(V, /double) / N ; where N is the number of elements in V
             SDEV    = SQRT ((Total(V^2) - N*AVERAGE^2)/ (N-1))
    
     EXAMPLE:
           Determine the xrange of structure, 9, and store in XR.
             STRINFO, 9, XRANGE = XR
           Determine the average and standard deviation of structure 14, Vector 1
             STRINFO, 14, AV1 = value
             AVERAGE = Value[0] & SDEV = Value[1]
    
     MODIFICATION HISTORY:
           Written by:     Paul Mix, February 23, 2006
           5/25/06         LPM, Added the AVn keywords
    
    

    (See ../pfidl/pfidl_2d/strinfo.pro)


    STRLIMITS

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           STRLIMITS
    
     PURPOSE:
           This procedure returns the parameters for a structure
    
     CALLING SEQUENCE:
           STRLIMITS, STR [, TYPE = type] [, FILE = file]
                [, CLABEL = clabel] [, TLABEL= tlabel]
                [, XRANGE = xrange] [, YRANGE = yrange] [, ZRANGE = zrange] 
                [, TRANGE = trange]
                [, V1 = v1] [, V2 = v2] [, V3 = v3] [, V4 = v4]
                [, V5 = v5] [, V6 = v6] [, V7 = v7] [, V8 = v8]
    
     INPUTS:
           STR:    Valid structure number, PFIDL structure, or search string 
                   for the structure comment
    	
     KEYWORD PARAMETERS:
           Note: Default values are 0 except for CLABEL
           TYPE:   Structure type 
           FILE:   File name for the data
           CLABEL: Structure Comment Label
           TLABEL: Structure Type Label
           XRANGE:	Range of X-values, or first dimension
           YRANGE:	Range of Y-values, or seconc dimension
           ZRANGE:	Range of Z-values, or third dimension
           TRANGE: Range of T-values, or fourth dimension
           V1:     Range of first vector component or attribute
           V2:     Range of second vector component or attribute
           V3:     Range of third vector component or attribute
           V4:     Range of fourth vector component or attribute
           V5:     Range of fifth vector component or attribute
           V6:     Range of sixth vector component or attribute
           V7:     Range of seventh vector component or attribute
           V8:     Range of eighth vector component or attribute
    
     OUTPUTS:
           Specified keyword parmeters are returned
    
     PROCEDURE:
           The specified structure is retrieved and the keyword parameters are 
           extracted.
    
     EXAMPLE:
           Determine the xrange of structure, 9, and store in XR.
             STRLIMITS, 9, XRANGE = XR
    
     MODIFICATION HISTORY:
           Written by:     Paul Mix, January 20, 2005
    
    

    (See ../pfidl/pfidl_2d/strlimits.pro)


    STRVALID

    [Previous Routine] [Next Routine] [List of Routines]
     Name: STRVALID
    
     NOTE: VALID is a flag to determine the mode of this routine.
    
         if keyword(valid) is not set.
         This function returns an array of valid structure array numbers.
         Minimum , maximum and a search string can be specified.
     or
         if keyword(valid) is set.
         This function returns an array of valid structure array number
         from a proposed array of numbers.
    
     Format:
       array = STRVALID([STRING] , [Maximum = maximum] [,Miminum = minimum]
               [,Npoint = npoint] [,case_sensitive = case_sensitive])
               [, VALID = valid] [, QUIET = quiet]
    
       where:
        IF VALID is zero or omitted:
             STRING is a search string. Leading and trailing blanks are ignored.
                    String may be a number. This routine uses:
                           str = strtrim(string(0), 2)
                      where str is the actual search string
                    For example s = strvalid(24.50) will return 
                       a structure with a comment   'Efield, t = 24.50 ns'
                    If missing, all valid arrays are returned.
                    See GET_MATCH for available wild card options.
             Minimum is the minimum value desired, Default = 1
             Maximum is the maximum value desired, Default = maxstructure
               Current version will sort maximum and minimum.
             Npoint is the number of values returned.
             Case_sensitive if set makes the search case sensitive.
             CAUTION: CASE is a special word so use /c or /ca or /cas or /case_
                      or more letters but /case will give an error.
        IF VALID is not zero:
             STRING  - an array of possible structure arrays.
                       Must be a byte, integer, long or a float variable.
                       Floats are converted to LONG using ROUND
                       This array of 1 or more numbers is not optional if 
                          VALID is set(ie not equal to zero or omitted).
                       See GET_MATCH for wild card options
                       or
                       A search string. If an array, only the first element is used.
             NPOINT  - the number of values returned.
             QUIET   - if set, not output will be generated.
                       if not set, messages will be printed if STRING contains
                         invalid structure arrays.
                        Messages of the form if VALID is a string:
                       "% "+STRTRIM(VALID, 2)+": "+ message
                  or   "% INVALID STR: " + message
               where message =
                    Structue array number is UNDEFINED
             or     Structure array must be a byte, integer, long, or float value 
             or     Structure array number must be greater than 0 and 

    (See ../pfidl/pfidl_2d/strvalid.pro)


    SUBSTR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           SUBSTR
    
     PURPOSE:
           Subtract a field structure array or a constant from 
            another a field structure array 
           Store the result in the initial field structure array or 
             another structure array
           All attribute or vector quantities are subtracted.
     CATEGORY:
           Math 
     CALLING SEQUENCE:
           SUBSTR, STR1, STR2,  [, STR3]
           SUBSTR, STR1, 0, VAR, [, STR3]
     INPUTS:
           STR1:    Structure or structure array number of the first structure
                    The output is the same form as the first structure.
                    If STR1 is an IDL structure and the result is to be saved
                      as an IDL structure in STR3 then the keyword: STRUCTURE
                      must be set and STR3 must be a variable.
           STR2:    Structure or structure array number of the second structure
      or
           0, VAR   Variable or constant to be subtracted from the first structure
     OPTIONAL INPUT:
           STR3:    array number for the sum, if not specified the 
                    difference is stored in STR1 (the first array)
     KEYWORDS:
           STRUCTURE: Optional keyword which must be present if an idl structure
                    is to be saved in the variable STR3. See example.
           CLABEL:  Optional label for the combined structures.
           MASTER:  Optional grid specification for single block, two dimensional
                    data.  Normally this type of data is put onto a uniform grid
                    with a spacing equal to the minimum spacing anywhere for either
                    grid.  If master = 1, the grid STR1 is used for the result;
                    STR2 is interpolated onto the grid of STR1.
                    If master = 2, then STR1 is interpolated onto the grid for
                    STR2 and the result has the same grid as STR2.
                    If MASTER is positive, the master grid will not be changed.
                    If MASTER is negative (or zero), the master grid will be
                    reduced to the region of overlap between STR1 and STR2.
                    For 3-Dimensional or multi-block data MASTER must be 1 or 2.
                      The data will be put onto the grid of either the first or
                      second structure array grid.  Missing values are set to zero.
           CUBIC:   If set a cubic interpolation will be used to match single
                    block data on different grids
     OUTPUTS:
           NONE    The difference is stored in a structure array in the 
                   structure common block
     COMMON BLOCKS:
           QSCOM.DAT QSSTRCOM.DAT
     RESTRICTIONS:
           STR1 array must be defined and have valid data
           STR2 or 0 and a Variable must be defined
         If master is specified, there are no additional restrictions.
           otherwise:
         If not a single block of data and two dimensions then:
           STR1 and STR2 must both be field arrays and have the same number
             of vector components.
           The SIZE of STR1 and STR2 must be the same
           The values of the spatial coordinates must be equal to about 
           3e-5(ie.- max(abs(difference))/max(value) lt 3.1e-5 )
           The check on spatial coordinates is done globally rather than 
             on a block by block basis.
           If a structure has three dimensions, but is degenerate in one of them
             that axis need not be equal.
         If a single block in two dimensions then the data will be interpolated to
           a common spatial scale using a cubic or bilinear interpolation.
     PROCEDURE:
           If STR1 or STR2 is a type 8 structure.
           If str.v1 has the same number of elements as str.v2 then:
             SUBSTR returns str1.v1-str2.v1 or str1.v1-VAR
               with the spacial values from STR1.
             If str1.nvect is lt str2.nvect the unmatched vectors from str2 are
               ignored.
    
         For type 1 structures:
           If STR2 is specified:
               Each vector component, of STR1 is subtracted from
                    each vector component of STR2
           If 0, VAR is specified:
               VAR is subtracted from each attribute of STR1
           In either case, the difference is stored in STR3, if specified,
               or STR1, if STR3 is not specified.
     EXAMPLES:
           Subtract structure arrays 2 and 3 and store the result in structure 8
                   SUBSTR, 2, 3, 8
           Subtract the variable OFFSET from structure array 2 and store the 
           difference in structure 8
                   SUBSTR, 2, 0, offset, 8
           Subtract structure arrays 3 and 8 and store the result in structure 10
           with a dataset comment, 'Total Charge - Line + Diode'
                   SUBSTR, 3, 8, 10, c=  'Total Charge - Line + Diode'
           Assume f is an idl structure.
                 SUBSTR, f, 2 ; Subtract f from Structure array 2 and return the 
                         difference as an idl structure in variable f.
                 SUBSTR, f, 2, 3 ; Subtract f from Structure array 2 and return 
                         the difference to structure array 3
                         Note: A warning will be printed. To avoid the warning use:
                                 i2s, f, 3 & addstr, 3, 2
                 SUBSTR, f, 2, g, /s ; Subtract f from Structure array 2 and 
                         return the difference as an idl structure in variable g
                      Note: If g is not a variable then the results will be lost.
    
     MODIFICATION HISTORY:
          Original version, L. P. Mix, JULY 15, 1993
          Added MASTER, CUBIC keywords in 1995.
    

    (See ../pfidl/pfidl_2d/substr.pro)


    T2W

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           T2W
    
     PURPOSE:
           Convert times in a Time-Dependent Finite-element Structure array 
             to a WDF array
           or 
           Convert times in a netCDF or PDB file to a WDF array
    
     CALLING SEQUENCE:
           T2W, STR [, WDF]
    
     INPUTS:
           STR:  Structure or structure array number of a type 9 structure 
                 Taken as WDF if a keyword is set.
           WDF:  WDF array number to store the function
                 Default: WDF = Get_MaxWDF()
    
     KEYWORD PARAMETERS:
           CDF:  If set, Time from the current netCDF file is taken
                 If set, STR is taken as WDF 
           PDB:  If set, Time from the current PDB file is taken
                 If set, STR is taken as WDF 
         Note: If CDF is set, PDB is not checked.
               If PDB is set, STR is assumed to be the WDF.
               If no keywords are set, STR is assumed to be a structure.
    
     OUTPUTS:
           Store the time data in a WDF array.
    
     COMMON BLOCKS:
           PDB and CDF common blocks are available
    
     RESTRICTIONS:
           A PDB or netCDF file must be open or a time dependent finite element
           array must be in memory.
    
     EXAMPLE:
           Convert the time array for structure 6 to WDF array #4.
              T2W, 6, 4
    
           Store the time values for the current PDB file in the maximum WDF array.
              T2W, /pdb
    
           Store the time values for the current netCDF file in WDF array 4
              T2W, 4, /cdf
    
     MODIFICATION HISTORY:
     	Written by:	L. P. Mix, December 22, 1999
    

    (See ../pfidl/pfidl_2d/t2w.pro)


    THERMOMETER

    [Previous Routine] [Next Routine] [List of Routines]
       Produce a thermometer type legend for a contour plot
       Unless the position keyword is used the thermometer will be on the right
         end or top of the current plot.
       Internals: The command uses a contour plot with X = [0, 1] and 
                  Y = Amplitude with the c_colors given by col_values, and 
                  FILL = 1 (See Procedure below)
       The values for the !x and !y variables are saved when this procedure
                  is called and are restored at completion.
       format: thermometer, amplitude, col_values, title = title, color= color, $ 
               position = position, /data, /horizontal,  absolute = absolute, 
               txsize = txsize, tysize = tysize, tickvalue = tickvalue, 
               cursor = cursor, bwhite = bwhite, ignore = ignore, 
               box = box, bfill = bfill,  cbox = cbox,
               thick = thick, charsize = charsize, _extra = extrastuff
       where
             AMPLITUDE - Array of values - typically levels of the contour plot
             Col_Values - Array of color values -
                         typically levels of the contour plot
             Note: Amplitude and Col-Values must have the same number of values.
             Exception  - If Amplitude has 3 values and Col_Values has 2 and 
                          amplitude(1) < amplitude(0) < amplitude(2) then
                          a two color thermometer will be drawn with col_values(0) 
                          below (or to the left of) amplitude(0) and 
                          col_values(1) above (or to the right of)amplitude(0)
                          See also /bwhite
             BWHITE    - If set, col_values is set to [!p.color, !p.background]
             COLOR     - Color for printing
                         Default is !p.color (white for X and Black for PostScript)
                         Values are: 1, red; 2, green; 3, blue; 4, magenta;
                         5, orange; 6, cyan; 7, yellow; 8, white; 0, black
             CURSOR    - If set the two opposite corners of the thermometer will 
                         be set with a cursor.  Normalized position will be 
                         returned in position.
             POSITION  - Position on the plot for the thermometer in units
                         determined by keywords. If position has valid data,
                         TXsize and TYsize are ignored.
                         If POSITION is undefined then the default is determined
                            by the value of txsize and tysize
                         POSITION will be returned with the values in normal 
                            coordinates 
             IGNORE    - Thermometer trys to adjust the title position to fit.
                         If it moves it to a bad location, use ignore.
                         If ignore is not equal to 1, then the position will be
                         moved an amount left or right given by the difference
                         between ignore and 1
                         Specifically: If middle is the location of the default
                         middle of the title, then middle is changed according to
                              middle = middle +(ignore -1.0)
             /data     - Determines the coordinates for the position keywork
                         Data refers to the plot coordinates 
                         If keyword is not set, then normalized space coordinates
                         are used.
                NOTE:  Normalized coordinates are relative to the plot not
                       then entire screen, ie, x = 1 will be the middle of the
                       screen or page if !p.multi (1) equals 2
             ABSOLUTE  - If present and not zero then position is normalized 
                         coordinates relative to the screen not the last plot
             /HORIZONTAL If keyword is set, thermometer will be horizontal.
                         If set, default value of TXsize = [.5, .9] and 
                         TYSIZE =[.3, .6]*(!y.window(0)-!y.region(0))+!y.region(0)
                         Default is vertical.
             TXsize    - If position is not specified, this parameter determines
                         the horizontal size of the thermometer and optionally the 
                         positional x values if TXsize is a two element vector.
                         Size in window units is TXsize*(!x.region(1)-!x.window(1))
                         Default is TXsize = 0.3
                         Default position is against the right border.
                         If two values are given, these are used as the two 
                         positional x parameters.
             TYsize     If position is not specified, this parameter determines the
                         vertical size of the thermometer and optionally the 
                         positional y values if TYsize is a two element vector.
                         If a single parameter is given, the height of the
                         thermometer will be given by:
                          TYsize*(!y.window(1)-!y.window(0))
                         Default value is TYsize = 0.6
                         Default position is vertically centered.
                         If two values are given, these are used as the two 
                         positional y parameters.
             Example:
                         TXsize and TYsize are two element arrays.
                         position = [txsize(0), tysize(0), txsize(1), tysize(1)]
             Thick     - parameter sent to plot, changes the thickness of the frame
             Charsize  - parameter sent to plot.
                         default is 1/max(!p.multi(1:2)-1)>1
             Box       - Draw a box around the thermometer if set.
                       - If Box has 4 elements, they will be taken as the position
                         of the box.
                         Otherwise the size will be estimated.
                         The color will be specified by CBOX
             CBOX      - Color of the BOX. Default is COLOR
             BFILL     - Fill the box with the specified color.
                         Note to erase an area: BFILL = !p.background
             Title     - Title for the thermometer. This may be a string array.
                         Each element is printed on separate lines. 
                         For a vertical thermometer the title will be centered over
                         an extension of the Y axis unless it will entend past the
                         edge of the plot region; otherwise it will be move left or
                         right to lie with the plot region.
                         For a horizontal thermometer, the title will be centered
                         over the thermometer.
             Tickvalue - Value where thermometer values are to be printed.
                         use /xstyle for horizontal and /ystyle for normal 
                         thermometers if exact scaling is desired.
             extrastuff- Any valid parameters for the plot command
                         xstyle or ystyle = 1 will force exact scaling
          Procedure:
         Set up the position if not specified and:       
              plot, amplitude, /nodata, position = position, $
                color = color, _extra = extrastuff, $
                xtickname =[' ', ' '], xticks= 1, xticklen = 1e-3 
         Determine the number of number and repeat as required the following:
              contour, data, [0, 1], amplitude, position= position, $
                color = color, c_color= col_values, levels = amplitude, $
                thick = thick
    
             Example:
               Add a thermometer to a contour plot of data in structure 23.
                 plotstr, 23, /thermometer 
    
               Add a thermometer to a E field plot from str 2 and scale the data.
               Take Er and slice the data at theta = 0.0 and plot 25 levels.
                 plotstr,2, 1, 2, 0.0, /thermometer, m = 1e-8, nl =25, $
                    ther ={title:['Er Field', '(MV/cm)']}, $
                 title= 'Radial Electric Field'
            or 
                lev = 0 &  color = -1 
                plotfld, 2, 1, 2, 0.0, color = color, nl = 25, level= lev, $
                  xmargin= [10, 10], title= 'Radial Electric Field'
                thermometer, lev*1e-8, color, title =['Er Field', '(MV/cm)']
    
              Add a thermometer to a plot with a range of [0, 10] and a value
                of 5.6 and color 1 below 5.6 and color 2 above 5.6; make a two
                line title of 'Diode Voltage (MV)'; use the cursor to place.
    
                thermometer, [5.6, 0, 10], [1,2], tit=['Diode','Voltage (MV)'], /cur
    
              Note: to change to horizontal merely add the ", /horizontal" keyword.
              To make a black and white thermometer merely change [1, 2] to 
                 [!p.color, !p.background] or set the keyword /bwhite as:
              thermometer,  [5.6, 0, 10], /bw, tit=['Diode', 'Voltage (MV)'], /cur
    
              Add a black and white thermometer to a plot which has a value of 
              volt(i) and ranges from 0 to 5.
                thermometer, [volt(i), 0, 5], /bw
    

    (See ../pfidl/pfidl_2d/thermometer.pro)


    TINDEX

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           TINDEX
    
     PURPOSE:
           Function to return the index for the closest specified time.
    
     CALLING SEQUENCE:
           IND = TINDEX(STR, TIME, /CDF, /PDB, /Valid)	
    
     INPUTS:
           STR:  Structure or structure array number of a type 9 structure 
                 Taken as TIME if a keyword is set.
           TIME: Time at which the closest index is desired.
           IF no keywords are set, both STR and TIME must be provided.
           If a keyword is set, STR is assumed to be TIME.
    
     KEYWORD PARAMETERS:
           VALID:If set, only valid values will be returned.
                 If time less than the initial time or greater than the final time
                 and valid is set, then -1 is returned. 
                Note: A fudge factor of 1/2^15 of the range is allowed.
                 If valid is omitted, then the closest time is returned.
           CDF:  If set, Time from the current netCDF file is taken
                 If set, STR is taken as TIME
           PDB:  If set, Time from the current PDB file is taken
                 If set, STR is taken as TIME
         Note: If CDF is set, PDB is not checked.
               If no keywords are set, STR is assumed to be a structure.
    
     OUTPUTS:
           IND:  INDEX for output time closest to TIME.
                 IND = -1 if an error occurs
                 IND is in the range [1, Ntime]
    
     COMMON BLOCKS:
           PDB and CDF common blocks are available
    
     RESTRICTIONS:
           A PDB or netCDF file must be open or a time dependent finite element
           array must be in memory.
    
     EXAMPLE:
           Determine the index closest to 11.1 ns from the current cdf file
              IND = tindex (11.1e-9, /cdf) 
    
           Determine the index closest to 12.3 ns in structure 4
              IND = tindex (4, 11.1e-9) 
    
           Plot the data in structure 3 at about 8ns.
              PLOTSTR, 3, TINDEX(3, 8e-9), /index
    
     	Written by:	L. P. Mix, December 22, 1999
    

    (See ../pfidl/pfidl_2d/tindex.pro)


    TOTFR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           TOTFR
    
     PURPOSE:
           Add the counts in a CR-39 digitized image.
           Input structure must be single block, 2 dimensions.
    
     CATEGORY:
           Math 
    
     CALLING SEQUENCE:
           Track_Total = TOTFR(STR_IN [, NX] [, NY] [, AREA = area] 
                                [, DENSITY = density] [, /PLOTIT ])
    
     Where:
           Track_Total - Total number of tracks in the designated area
                         If NX is present and > 0, NX*NY values will be returned
                         If NX is zero or omitted, Track_Total is a scalar value
           STR_IN    - Structure or structure array number with the CR-39 image.
                       This may be any 2 dimensional, single block, scalar structure
           NX        - Number of images in the horizontal direction.
                       If NX is omitted, zero or negative, then the user will be
                       asked to designate a single area.
           NY        - Number of frames in the vertical direction.
                       Ignored if NX is not positive.
                       Default value = 1.
           AREA      - Keyword returned with the area = Sx*Sy*Dx*Dy
                       Where Sx and Sy are the size in bins in the X and Y 
                       directions of each image and Dx and Dy are the size of the
                       bins.  AREA is a scalar quantity.
           DENSITY   - Average number of Tracks /unit area.  = Track_Total/AREA
           PLOTIT    - If set, Image will be plotted.
    
     BACKGROUND:
           CR-39 images are digitized according to the number of tracks with a
           given size in a bin. Low resolution scans are 300 microns/bin.
           High resolution scans are 150 microns/bin.
    
      Frame Number       Track Area (Pixels = 0.299 um^2) / Effective Diam.
             1                 1 to 2 pixels    /  0.617 to 0.872 microns
             2                 3 to 5 pixels    /  1.069 to 1.380 microns
             3                 6 to 10 pixels   /  1.511 to 1.951 microns
             4                11 to 16 pixels   /  2.046 to 2.468 microns
             5                17 to 23 pixels   /  2.544 to 2.959 microns
             6                24 to 32 pixels   /  3.023 to 3.490 microns
             7                33 to 42 pixels   /  3.544 to 3.999 microns
             8                43 to 53 pixels   /  4.046 to 4.492 microns
             9                54 to 65 pixels   /  4.534 to 4.974 microns
            10                66 to 94 pixels   /  5.013 to 5.982 microns
            11                95 to 128 pixels  /  6.014 to 6.981 microns
            12               129 to 168 pixels  /  7.008 to 7.997 microns
            13               169 to 212 pixels  /  8.021 to 8.984 microns
            14               213 to 262 pixels  /  9.005 to 9.987 microns
            15               263 to 378 pixels  / 10.006 to 11.996 microns
            16               379 to 514 pixels  / 12.012 to 13.989 microns
            17               515 to 672 pixels  / 14.002 to 15.995 microns
            18               673 to 851 pixels  / 16.007 to 17.999 microns
            19               852 to 9999 pixels / 18.010 to  112.832 microns
            20               Saturation Frame - Total Number of Pixels with tracks
                                                normalized to the number of pixels
                                                in the bin times 32768.
                        (a value of 16384 means half of the pixels contain tracks)
    
     EXAMPLES:
           Calculate the total number of tracks for the entire structure 1.
             tracks = totfr(1, 1)
    
           Calculate the number of tracks in each of 6 images in structure 2 
           which are arranged in a 3 horizontal by 2 vertical array.
              tracks = totfr(1, 3, 2)
            NOTE: tracks = tracks[3,2]
    
    
     MODIFICATION HISTORY:
          Original version, L. P. Mix, November 16, 1998
    

    (See ../pfidl/pfidl_2d/totfr.pro)


    TRIFL[1]

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
    	TRIFL
    
     PURPOSE:
    	Model electromagnetic energy transport in a transmission line
           Source voltages are either from a WDF array or analytic
           Loads are Constant Impedance or perveance, analytic falling
             impedance, analytic rising then falling, impedance from a
             wdf array, or an imploding plasma load
           Electron flow in the MITL is assumed to occur by default.
             Electron flow can be turned for the entire MITL or up to a
             point on the transmission line.  After flow is turned on, it 
             will be on until the load.
    
     CALLING SEQUENCE:
    
           TRIFL [, X ,ZVAC] [, Zflow] [, Transition = TR] [, OUT = out]
             [,CONVOLUTE = convolute] [, FLOWOUT = flowout]
       TRIFL [, WD_ZV] [, WD_ZF]  [Transition = TR] [, OUT = out]
             [,CONVOLUTE = convolute] [, FLOWOUT = flowout]
       TRIFL [, X, Y]  [Transition = TR] [, OUT = out]
             [,CONVOLUTE = convolute] [, FLOWOUT = flowout]
    
     REQUIRED INPUTS:
    	None - The user is normally prompted for TRIFL line segments.
                  The parameters which the user must specify are listed in a 
                    window interface.
    
     OPTIONAL INPUT:
           NOTE:   X values cannot be closer than 1e-5 of the largest value
                   Values closer than this will be averaged.
                   All dimensions are meters/ohms
           X, Zvac, Zflow - 
                    At least 2 arrays must be provided and have the same number of 
                      elements where :
                    X - spatial coordinate
                    Zvac - Vacuum Impedance
                    Zflow - Flow impedance (In general, ignored and calculated 
                      according to the formula:Zflow = Zvac*v/(v+2Me) where
                      Me is 0.511 kV and v is the peak voltage on the line.
                      At a convolute Zflow is held constant until then convolute 
                      region and allow to transition to the downstream value.
           WD_Zv, WD_Zflow -
                    Waveform array numbers for the vacuum impedance and the 
                    flow impedance. (See Zflow above- largely ignored)
           NOTE:    Linear interpolation will be used to connect input points.
    
           X, Y  -  Arrays from the READASC command
                    If Y has 3 values in the second dimension then Tr = Y(*, 2)
                    X  - spatial coordinate
                    Y(*,0) - Zv - Vacuum Impedance
                    Y(*,1) - Zflow  - Flow impedance
                       (See Zflow above- largely ignored)
           Transition - A single element or an array indicating the type of 
                    transition between tranmission line segments.  If TR is an 
                    array it must have the same number of elements as X. If
                    waveform arrays are provided, linear interpolation will be
                    used to put the waveforms on a common time scale.
                    Values are:
                        0 Linear (DEFAULT)
                        1 Sine^2
                        2 Log
            OUT     Starting point for WDF arrays and Structure Arrays
                    Default is OUT = 1
            CONVOLUTE - An array of values corresponding to the convolute flow 
                        impedance; a zero value indicates no convolute
            FLOWOUT   - Flow impedance on the output of a convolute; a zero
                        value indicates no convolute.
            Note:   The environment variable "TRIFL_EXE" will be used as the 
                    executable if it is specified.
    
     OUTPUTS:
    	Three files are written: 
             1. Suffix of ".geom" is an ASCII geometry file for the TRIFL
             2. Suffix of ".src" is an ASCII source file for the TRIF code
    	  3. Suffix of ".pff" is the calculated data for the TRIFL run
                The first dataset is an IFL dataset.
                The integer array has the load type and the electron flow
                   flag.
                The float list has the source inpedance for the driver and,
                   in the case of a Imploding Plasma Load, it has the following:
                       Mass/Length, Length, Initial Radius, % to Final Radius, 
                       Return Radius, L0, Lstart, I0
     The following WDF arrays are populated for OUT=1 and a Imploding Plasma Load:
           Array No.   Dataset Comment
                  1    Load Voltage vs Time
                  2    Load Current vs Time
                  3    Input Voltage vs Time
                  4    Input Current vs Time
                  5    dL/dt - Change in Inductance vs Time
                  6    Inductance vs Time
                  7    Forward Going Voltage
                  8    Forward Going Power vs Time
                  9    Forward Going Energy vs Time
                 10    Input Energy vs Time
                 11    Output Energy vs Time
                 12    Inductive Load Energy vs Time
                 13    Net Foil Energy vs Time
                 14    Total Efficiency (wdf 13/wdf9 * 100)
     For a resistive load the arrays are:
           Array No.   Dataset Comment
                  1    Load Voltage vs Time
                  2    Load Current vs Time
                  3    Input Voltage vs Time
                  4    Input Current vs Time
                  5    Forward Going Voltage
                  6    Forward Going Power vs Time
                  7    Forward Going Energy vs Time
                  8    Input Energy vs Time
                  9    Output Energy vs Time
                 10    Total Efficiency (wdf 9/wdf7 * 100)
     The following structure arrays are populated for OUT = 1
          Array No.   Dataset Comment
                1     A - 
                2     V - 
                3     Q - 
                4     Ie - 
                5     Ia - 
                6     Ic - 
                7     Qa -
                8     Qc -
    
     COMMON BLOCKS:
    	The transmission line data is stored in a common block: MITL_common
    
     PROCEDURE:
    	Technique developed by C. W. Mendel with some modifications by L. P. Mix
           and D. B. Seidel.
           Each transition line section will need the vacuum impedance as a
             function of axial impedance.
    
     EXAMPLE:
    		TRIFL
    
     MODIFICATION HISTORY:
     	Written by:	L. P. Mix, June 28, 1994
                           Added convolutes, June 7, 1995
    
    

    (See ../pfidl/pfidl_2d/trifl.pro)


    TRIFL[2]

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
    	TRIFL
    
     PURPOSE:
    	Model electromagnetic energy transport in a transmission line
           Source voltages are either from a WDF array or analytic
           Loads are Constant Impedance or perveance, analytic falling
             impedance, analytic rising then falling, impedance from a
             wdf array, or an imploding plasma load
           Electron flow in the MITL is assumed to occur by default.
             Electron flow can be turned for the entire MITL or up to a
             point on the transmission line.  After flow is turned on, it 
             will be on until the load.
    
     CALLING SEQUENCE:
    
           TRIFL [, X ,ZVAC] [, Zflow] [, Transition = TR] [, OUT = out]
             [,CONVOLUTE = convolute] [, FLOWOUT = flowout]
       TRIFL [, WD_ZV] [, WD_ZF]  [Transition = TR] [, OUT = out]
             [,CONVOLUTE = convolute] [, FLOWOUT = flowout]
       TRIFL [, X, Y]  [Transition = TR] [, OUT = out]
             [,CONVOLUTE = convolute] [, FLOWOUT = flowout]
    
     REQUIRED INPUTS:
    	None - The user is normally prompted for TRIFL line segments.
                  The parameters which the user must specify are listed in a 
                    window interface.
    
     OPTIONAL INPUT:
           NOTE:   X values cannot be closer than 1e-5 of the largest value
                   Values closer than this will be averaged.
                   All dimensions are meters/ohms
           X, Zvac, Zflow - 
                    At least 2 arrays must be provided and have the same number of 
                      elements where :
                    X - spatial coordinate
                    Zvac - Vacuum Impedance
                    Zflow - Flow impedance (In general, ignored and calculated 
                      according to the formula:Zflow = Zvac*v/(v+2Me) where
                      Me is 0.511 kV and v is the peak voltage on the line.
                      At a convolute Zflow is held constant until then convolute 
                      region and allow to transition to the downstream value.
           WD_Zv, WD_Zflow -
                    Waveform array numbers for the vacuum impedance and the 
                    flow impedance. (See Zflow above- largely ignored)
           NOTE:    Linear interpolation will be used to connect input points.
    
           X, Y  -  Arrays from the READASC command
                    If Y has 3 values in the second dimension then Tr = Y(*, 2)
                    X  - spatial coordinate
                    Y(*,0) - Zv - Vacuum Impedance
                    Y(*,1) - Zflow  - Flow impedance
                       (See Zflow above- largely ignored)
           Transition - A single element or an array indicating the type of 
                    transition between tranmission line segments.  If TR is an 
                    array it must have the same number of elements as X. If
                    waveform arrays are provided, linear interpolation will be
                    used to put the waveforms on a common time scale.
                    Values are:
                        0 Linear (DEFAULT)
                        1 Sine^2
                        2 Log
            OUT     Starting point for WDF arrays and Structure Arrays
                    Default is OUT = 1
            CONVOLUTE - An array of values corresponding to the convolute flow 
                        impedance; a zero value indicates no convolute
            FLOWOUT   - Flow impedance on the output of a convolute; a zero
                        value indicates no convolute.
            Note:   The environment variable "TRIFL_EXE" will be used as the 
                    executable if it is specified.
    
     OUTPUTS:
    	Three files are written: 
             1. Suffix of ".geom" is an ASCII geometry file for the TRIFL
             2. Suffix of ".src" is an ASCII source file for the TRIF code
    	  3. Suffix of ".pff" is the calculated data for the TRIFL run
                The first dataset is an IFL dataset.
                The integer array has the load type and the electron flow
                   flag.
                The float list has the source inpedance for the driver and,
                   in the case of a Imploding Plasma Load, it has the following:
                       Mass/Length, Length, Initial Radius, % to Final Radius, 
                       Return Radius, L0, Lstart, I0
     The following WDF arrays are populated for OUT=1 and a Imploding Plasma Load:
           Array No.   Dataset Comment
                  1    Load Voltage vs Time
                  2    Load Current vs Time
                  3    Input Voltage vs Time
                  4    Input Current vs Time
                  5    dL/dt - Change in Inductance vs Time
                  6    Inductance vs Time
                  7    Forward Going Voltage
                  8    Forward Going Power vs Time
                  9    Forward Going Energy vs Time
                 10    Input Energy vs Time
                 11    Output Energy vs Time
                 12    Inductive Load Energy vs Time
                 13    Net Foil Energy vs Time
                 14    Total Efficiency (wdf 13/wdf9 * 100)
     For a resistive load the arrays are:
           Array No.   Dataset Comment
                  1    Load Voltage vs Time
                  2    Load Current vs Time
                  3    Input Voltage vs Time
                  4    Input Current vs Time
                  5    Forward Going Voltage
                  6    Forward Going Power vs Time
                  7    Forward Going Energy vs Time
                  8    Input Energy vs Time
                  9    Output Energy vs Time
                 10    Total Efficiency (wdf 9/wdf7 * 100)
     The following structure arrays are populated for OUT = 1
          Array No.   Dataset Comment
                1     A - 
                2     V - 
                3     Q - 
                4     Ie - 
                5     Ia - 
                6     Ic - 
                7     Qa -
                8     Qc -
    
     COMMON BLOCKS:
    	The transmission line data is stored in a common block: MITL_common
    
     PROCEDURE:
    	Technique developed by C. W. Mendel with some modifications by L. P. Mix
           and D. B. Seidel.
           Each transition line section will need the vacuum impedance as a
             function of axial impedance.
    
     EXAMPLE:
    		TRIFL
    
     MODIFICATION HISTORY:
     	Written by:	L. P. Mix, June 28, 1994
                           Added convolutes, June 7, 1995
    
    

    (See ../pfidl/pfidl_2d/triflw.pro)


    UNIONSTR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           UNIONSTR
    
     PURPOSE:
           Combine two structures into a composite structure.
           Both structures should have the same block structure.
           All vector quantities in the region of overlap are added.
           Note: If the quantities have identical blocks and grid data, then 
                 the results will be identical to ADDSTR
     CATEGORY:
           Math 
     CALLING SEQUENCE:
           UNIONSTR, STR1, STR2,  [, STR3]
     INPUTS:
           STR1:    Structure or structure array number of a Type 1 structure
           STR2:    Structure or structure array number of a Type 1 structure
     Note: STR1 and STR2 should have the same block configuration as described 
           in the procedure.  
           STR1 and STR2 must both have the same number of dimensions.
     OPTIONAL INPUT:
           STR3:    array number for the sum, if not specified the 
                     sum is stored in STR1 (the first array)
                     The form of STR3 is the same as STR1.
     KEYWORDS:
           CLABEL:  Optional label for the combined structures.
     OUTPUTS:
           NONE    The sum is stored in a structure array in the common block
     COMMON BLOCKS:
           QSCOM.DAT QSSTRCOM.DAT
     RESTRICTIONS:
           STR1 and STR2 arrays must be defined and have valid data.
           STR1 and STR2 should have the same block structure.
           Number of dimensions, NDIM, should be less than 4.
     PROCEDURE:
           Begin with the first block in STR1 and determine if STR2 has any blocks
             which overlap this block.  The block will be enlarged to include all 
             data.  Data from STR1 and STR2 which overlap will be added.
             A minimum of 4 points are required to add a block.
           This procedure will be repeated for each block in STR1. 
           If STR2 has blocks which have not been included in the UNION structure,
             they will be added.
           Equal is defined with an allowance of 2^(-15) (3.05176e-05) of the
             range of the data.
           Both structures should have the same grid values, but only the total
             number of values between two grid limits is checked.
     EXAMPLES:
           Combine structure arrays 2 and 3 and store the result in structure 8
                   UNIONSTR, 2, 3, 8
    
           Add structure arrays 3 and 8 and store the result in structure 10
           with a dataset comment, 'Total Charge - Line + Diode'
                   UNIONSTR, 3, 8, 10, c=  'Total Charge - Line + Diode'
     MODIFICATION HISTORY:
          Original version, L. P. Mix, JULY 5, 2000
    

    (See ../pfidl/pfidl_2d/unionstr.pro)


    VIDA2STR[1]

    [Previous Routine] [Next Routine] [List of Routines]
       Convert a vida image to a PFIDL structure
       Format:
         vida2str, vida, str [, /structure] [, CLABEL = clabel]
               [dx = dx, dy = dy, dz = dz]
    
         where:
              VIDA   - Vida data type 
                       1 = Film Intensity
                       2 = Film Density
                       3 = 
              STR    - Variable name or a structure array number
              STRUCTURE - If set then data is returned in STR.
                          If not set then data is stored in a structure array.
              CLABEL - Label used for dataset comment. 
                       Default is Title_1
              DX, DY, DZ - Axis spacing for each dimension
          Example:
              Make a structure array from the current intensity array in vida
                  and store in picture; use dataset description 'Filtered Image'
                vida2str, 1, picture, clab = 'Filtered Image', /structure
    
              Store in structure array, 3, the current density image in vida
                vida2str, 2, 3
    
    

    (See ../pfidl/pfidl_2d/vida2str.pro)


    VIDA2STR[2]

    [Previous Routine] [Next Routine] [List of Routines]
     Common block for film density information.
    

    (See ../pfidl/pfidl_2d/vida2str.pro)


    VIDA2STR[3]

    [Previous Routine] [Next Routine] [List of Routines]
     Common block for title information
    

    (See ../pfidl/pfidl_2d/vida2str.pro)


    VIDA2STR[4]

    [Previous Routine] [Next Routine] [List of Routines]
     Common block analysis information
    

    (See ../pfidl/pfidl_2d/vida2str.pro)


    VIDA_AXIS

    [Previous Routine] [Next Routine] [List of Routines]
      Modify the AXIS scaling of VIDA data
        Vida stores offsets in mm and dx in microns.  This routine takes the
        initial point and changes the dx by a factor of 1000.
    
      Format:  VIDA_AXIS, STR1 [, STR2]
      where:
        STR1, STR2 - Structure array numbers
        Data in STR1 is converted and stored in STR2.
        If STR2 is missing, then data is stored in STR1.
        Data must be type 1 field data.
    
      Example:
      Fix data in structure 4 and return to structure 4.
        VIDA_AXIS, 4
    
      Fix data in structure 5 and return to structure 6.
        VIDA_AXIS, 5, 6
    

    (See ../pfidl/pfidl_2d/vida_axis.pro)


    WARP_IMAGE

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           Warp_Image
    
     PURPOSE:
           Change the dimensions of an image or single block field dataset.
             Y scaling is a function of X or conversely.
           Only single block, type 1 (Rectilinear), data is supported.
     CATEGORY: 
           Utility 
     CALLING SEQUENCE: 
           Warp_Image, STR
     INPUTS: 
           STR:      Structure array or Structure Array Number
    
     KEYWORD PARAMETERS:
       Note: POLY in the descriptions below takes an array X and Coefficients C
             and calculates: POLY(X,C)= C[0] + X*C[1] + X*X*C[2] + ... +X^(M)*C[M]
             where M = N_Elements(C)-1
    
           TRANSPOSE:  Scale X according to the Y value.
                     Default: Y = Y(F(X))
           MDIM:     Multiply the current axis values by this coefficient or 
                     array of coefficients.
                     Example: 
                       Y is current set of dimensions
                       Ynew = Y*POLY(X, Mdim) is the new set of dimensions
                       Xnew = [0, total(dx/DX, /cum)
               Note: Present version may not handle any function (MDIM values) which
                     do not preserve the order of YNEW.
           Conserve: Preserve the total integral over the image.
                     Set this if the image represents a film value and a smaller value
                     of DY represents a higher value at the target.
           LABEL:    Replace the DIM axis label with this string.
           Keep_all: Replace STRARRAY with a finite element structure
                     Default:  Uniform Y scale between Max and Min with same number of points.
     OUTPUTS:
           Rescaled structure.
                   
     COMMON BLOCKS:
           QSCOM, QSSTRCOM 
     RESTRICTIONS:
           STR array must be defined and have valid data
           DIM must be specified
           Mdim must be specified.
    
     EXAMPLES:
           Add .1 + 0.01*X to every Y value in structure 2
                WARP_Image, 2, 2, mdim =[0.1, 0.01]
    
     MODIFICATION HISTORY:
          Original version, L. P. Mix, June 1, 2004
    

    (See ../pfidl/pfidl_2d/warp_image.pro)


    WINSTR

    [Previous Routine] [Next Routine] [List of Routines]
     NAME:
           WINSTR 
    
     PURPOSE:
           Window a 2-D structure - Similar to WIN for a waveform
           Single block data generally uses the actual data for window.
           Multiple block data is put on a uniform grid with 1 pixel resolution.
           Procedure will generate windowed regions and display them. 
           The designated windowed regions will be stored in structure arrays.
           A preview gives the window before storage. A preview will be generated
             whenever the mouse moves in the window and one point has been 
             selected.  The preview frame may be resized.
           Note: Some time is required to calculate a preview frame. All events
                 generated while the preview frame is generated are deleted; be
                 sure the mouse clicks are acknowledged before proceeding.
           Mouse buttons are mapped to widget buttons, cursor must be in the 
             DRAW area of the main widget for the following mouse commands.
              Left Button   = Set Value
                 Note: A carriage return in the data field will also set the value.
              Middle Button = Accept/Save
                 (current designated windowed image will be saved)
              Right Button  = Reset All Points
                 (All points will be undesignated)
              Note: If a the last point required to define a curve is selected 
                    more than once, the previous "last point" is replaced.
           Set Point Buttons: These perform the same function as a  in either
                              the X or Y windows above the buttons.
    
     CALLING SEQUENCE:
    	WINSTR, STR [, X, Y]
       where:
           STR   - Structure array number of a two dimensional structure or 
                   a slice from three dimensional structure.
                   This structure will be overwritten if save is not specified.
                   The structure should be single block for best results. Multi-
                   block structures will be put on a uniform 256 by 256 grid.
                   To use an interpolation with N elements use:
                     PLOTSTR, STR, NFARRAY = N, RESULT = STR2
                     WINSTR, STR2
                   Note: Data will not be transposed.
                   Note: If STR is a structure, data will be saved in the first
                         unused structure array or in the maximum.
             
        BATCH mode:
           X, Y  - 2N X-values and 2N Y-values 
                   Windows of arbitrary pairs of points may be obtained in
                   batch mode where N is the number of regions desired
    
     KEYWORD PARAMETERS:
           SAVE:       Array of structure array numbers where subregions are 
                       stored.  
                       Default is smallest unused structure or maxstructure.
           PREVIEW:    If present and zero, no preview will be generated.
           STRarray:   Array of Structure array numbers where images are stored.
                       If no images are stored, then STRarray = 0
           CPRINT:     If set, print the dataset comment for each window structure 
                       to the terminal
           KEEP_ASPECT: Keep same aspect ratio in the preview window as in the
                       primary window.  Default: KEEP_ASPECT = 0
                       If KEEP_ASPECT is negative, the color map will also be kept.
           AVERAGE:    Average value (mean) of the saved array
           SDEVIATION: Standard deviation of the average.
                       SDEVIATION = sqrt((Total(X*X)-Total(X)*Total(X)/N)/(N-1))
                         where N is the number of points
                       NOTE: SDEVIATION is not shown on the widget.
           MINIMUM:    Minimum value of the saved array
           MAXIMUM:    Maximum value of the saved array
           _EXTRA:     Any valid keyword for plotfld. The array for the windowing
                       is generated with the following command and this plot is 
                       used for the image:
              PLOTFLD, str, nfarray=256, xarray = x, yarray = y, farray = array, $
                     nlev = 29,  _extra = extrastuff
             Note: nfarray is ignored with single block data
     EXAMPLE:
    	Take a series of images from structure array 3 and store the images
             beginning in structure array 11.
               WINSTR, 3, save = 11
    
           Take an image from (0, 0) to (3, 3) of structure 82 and store the result
             in structure 4
           
             WINSTR, 82,save= 4, [0, 3], [0, 3]
    
     MODIFICATION HISTORY:
     	Written by:	L. P. Mix, July 31, 2000
    

    (See ../pfidl/pfidl_2d/winstr.pro)


    WRIMSD

    [Previous Routine] [Next Routine] [List of Routines]
        Write a structure array to an ascii file
        This procedure limited to single block, single vector field data
        All labels are limited to 80 characters.
        format is:  WRIMSD, fname [, STR] [, VIDA = vida] [, CLABEL = clabel]
        where 
          fname   - the file name
                    If fname = 0 then fname ='PFIDLdefault.dat' 
          STR     - STR array or STR array number
                    If STR is not provided, then keyword VIDA must be set.
          VIDA    - Keyword indicating that VIDA data is to be put into a 
                    structure.
                    See VIDA2STR for values. The following command is called:
                    VIDA2STR, VIDA, STR, /STRUCTURE
          CLABEL  - Comment label for the output
        Example:
        Write STR array 5 into file 'PFIDLdefault.dat'
           WRIMSD, 0, 5
    
        Write STR 3 to file, 'testdata' 
           WRIMSD , 'testdata', 3
    
        form of file:
          dataset comment
          ndim, lcuniform 
          x axis label 
          y axis label
          z axis label
          nx, ny, nz
          x0, y0, z0 |
          dx, dy, dz |  or x, y, z
          field data
    
      where:
          ndim       = 2 or 3
          lcuniform  = 1 if uniform, 0 if not uniform
      X is uniform if max(dx)-min(dx) is less than 1.22e-4 *max(abs(x))
          axis label = string for axis labels
                       Z label is omitted if ndim = 2
          nx, ny, nz = number of elements in each dimension
                       (NZ omitted if ndim = 2)
          x0, y0, z0 = initial axis values
          dx, dy, dz = axis step size
          x, y, z    = axis values (lcuniform = 0)
                       dz or Z omitted if ndim = 2
          field data = image values
    
       Fortran read:
           integer lu, ndim, lcuniform, nx, ny, nz, i, j, k
           real x(:), y(:), z(:)
           real x0, y0, z0, dx, dy, dz 
           real image( :, :, :)
           character*80 xlabel, ylabel, zlabel, title
     c1     format (a)
           open(file = , unit = lu)
           read(lu, 1) title
           read(lu, *) ndim, lcuniform 
           read(lu, 1) xlabel
           read(lu, 1) ylabel
           nz = 1
           if (ndim .eq. 3) then
             read(lu, 1) zlabel
             read(lu, *) nx, ny, nz
           else
             read(lu, *) nx, ny
           endif 
     c      if fortran 90, allocate x, y, z, image
           if (lcuniform .eq. 0) then
             read(lu, *) (x(i), i = 1, nx)
             read(lu, *) (y(i), i = 1, ny)
             if (ndim .eq. 3) read(lu, *) (z(i), i = 1, nz)
           else
             if (ndim .eq. 2) then
               read(lu, *) x0, y0
               read(lu, *) dx, dy
             else
               read(lu, *), x0, y0, z0
               read(lu, *) dx, dy, dz
             endif
     c        can make x, y, z if desired x(i)= (i-1)*dx + x0, etc.
          endif
          read(lu, *)(((image(i, j, k),i=1,nx),j=1, ny),z=1,nz)
          close (lu)
    

    (See ../pfidl/pfidl_2d/wrimsd.pro)


    WRIMSD_EXT

    [Previous Routine] [Next Routine] [List of Routines]
        Write a structure array to an ascii file
        This procedure uses only IDL procedures
        This procedure limited to single block, single vector field data
        All labels are limited to 80 characters.
    
        Format:  WRIMSD_ext, fname, ARRAY  [, X] [, Y] [, Z]
                 [, DX = dx] [, DY = dy] [, DZ = dz] [, CLABEL = clabel]
                 [, XLABEL = xlabel] [, YLABEL = ylabel] [, ZLABEL = zlabel] 
        where 
          fname   - the file name
                    If fname = 0 then fname ='PFIDLdefault.dat'
          ARRAY   - Image array
          X       - X values 
                    If DX > 0 then X = X[0] and used as an initial value
          Y       - Y values
                    If DY > 0 then Y = Y[0] and used as an initial value
          Z       - Z values
                    If DZ > 0 then Z = Z[0] and used as an initial value
          DX      - If uniform data, the point spacing in the X direction
          DY      - If uniform data, the point spacing in the Y direction
          DZ      - If uniform data, the point spacing in the Z direction
          CLABEL  - Comment label
          XLABEL  - X Label
          YLABEL  - Y Label
          ZLABEL  - Z Label
    
        Example:
        Write ARRAY into file 'PFIDLdefault.dat'
           WRIMSD_ext, 0, ARRAY
    
        Write ARRAY into file 'testdata'
           WRIMSD_ext , 'testdata', ARRAY
    
        form of file:
          dataset comment
          ndim, lcuniform 
          x axis label 
          y axis label
          z axis label
          nx, ny, nz
          x0, y0, z0 |
          dx, dy, dz |  or x, y, z
          field data
    
      where:
          ndim       = 2 or 3
          lcuniform  = 1 if uniform, 0 if not uniform
      X is uniform if max(dx)-min(dx) is less than 1.22e-4 *max(abs(x))
          axis label = string for axis labels
                       Z label is omitted if ndim = 2
          nx, ny, nz = number of elements in each dimension
                       (NZ omitted if ndim = 2)
          x0, y0, z0 = initial axis values
          dx, dy, dz = axis step size
          x, y, z    = axis values (lcuniform = 0)
                       dz or Z omitted if ndim = 2
          field data = image values
    
       Fortran read:
           integer lu, ndim, lcuniform, nx, ny, nz, i, j, k
           real x(:), y(:), z(:)
           real x0, y0, z0, dx, dy, dz 
           real image( :, :, :)
           character*80 xlabel, ylabel, zlabel, title
     c1     format (a)
           open(file = , unit = lu)
           read(lu, 1) title
           read(lu, *) ndim, lcuniform 
           read(lu, 1) xlabel
           read(lu, 1) ylabel
           nz = 1
           if (ndim .eq. 3) then
             read(lu, 1) zlabel
             read(lu, *) nx, ny, nz
           else
             read(lu, *) nx, ny
           endif 
     c      if fortran 90, allocate x, y, z, image
           if (lcuniform .eq. 0) then
             read(lu, *) (x(i), i = 1, nx)
             read(lu, *) (y(i), i = 1, ny)
             if (ndim .eq. 3) read(lu, *) (z(i), i = 1, nz)
           else
             if (ndim .eq. 2) then
               read(lu, *) x0, y0
               read(lu, *) dx, dy
             else
               read(lu, *), x0, y0, z0
               read(lu, *) dx, dy, dz
             endif
     c        can make x, y, z if desired x(i)= (i-1)*dx + x0, etc.
          endif
          read(lu, *)(((image(i, j, k),i=1,nx),j=1, ny),z=1,nz)
          close (lu)
    

    (See ../pfidl/pfidl_2d/wrimsd_ext.pro)


    XFRSTR

    [Previous Routine] [Next Routine] [List of Routines]
      Generates a duplicate Structure array in a second structure array.
      WDF array labels, file name, etc. are also copied to the new WDF array.
      Format:  XFRSTR, STR1, STR2
      where:
        STR1, STR2 - Structure array numbers
      Example:
      Copy structue array 4 to array 5
        xfrstr , 4, 5 
    

    (See ../pfidl/pfidl_2d/xfrstr.pro)


    XLINEOUT

    [Previous Routine] [Next Routine] [List of Routines]
      Calculate a lineout of a two dimensional array at a given y value and 
        over a specified width.
      Format is: line = xlineout(array, yarray, yvalue [, width] [, /MEDIAN] $
             [, /INTEGRAL )
        where;
          LINE    - array of ordinate values for the lineout
          ARRAY   - two dimensional array
          YARRAY  - Ordinate values for array
          YVALUE  - Ordinate value at the center of the lineout
          WIDTH   - Width over which the values of array are averaged to 
                    obtain the values in LINE. Default is 0.0
             Note:  Average is spatially weighted 
                    Average = integral (array)/(upper - lower)
          MEDIAN  - If set and WIDTH > 0 then the median is returned.
          INTEGRAL- If set and WIDTH > 0 then the integral is returned.
                    Note:  If median is set, INTEGRAL is ignored
      Example:
        Obtain a horizontal lineout from ARRAY with ordinate values, Y, at 
        a value of y= AMAX.
          line = xlineout(array, y, amax)
        Note:  Since width is zero, value is simple interpolation.
    
        Obtain a horizontal lineout from PICTURE with ordinate values, Y, at
        a value of y= yy(i), averaged over a width of 0.06
          line = xline(picture, y, yy(i), 0.06)
    

    (See ../pfidl/pfidl_2d/xlineout.pro)


    YLINEOUT

    [Previous Routine] [Next Routine] [List of Routines]
      Calculate a lineout of a two dimensional array at a given x value and 
        over a specified width.
      Format is: line = ylineout(array, xarray, xvalue [, width] [, /MEDIAN]  $
             [, /INTEGRAL )
        where;
          LINE    - array of ordinate values for the lineout
          ARRAY   - two dimensional array
          XARRAY  - Abscissa values for array
          XVALUE  - Abscissa value at the center of the lineout
          WIDTH   - Width over which the values of array are averaged to 
                    obtain the values in LINE. Default is 0.0
             Note:  Average is spatially weighted 
                    Average = integral (array)/(upper - lower)
          MEDIAN  - If set and WIDTH > 0 then the median is returned.
          INTEGRAL- If set and WIDTH > 0 then the integral is returned.
                    Note:  If median is set, INTEGRAL is ignored
      Example:
        Obtain a horizontal lineout from ARRAY with abscissa values X at a 
        value of x = AMAX
          line = ylineout (array, x, amax)
        Note:  Since width is zero, value is simple interpolation.
    
        Obtain a horizontal lineout from PICTURE with abscissa values, X, at
        a value of x= xx(i), averaged over a width of 0.06
          line = xlineout(picture, x, xx(i), 0.06)
    

    (See ../pfidl/pfidl_2d/ylineout.pro)


    ZOOMS

    [Previous Routine] [List of Routines]
     NAME:
    	ZOOMS
    
     PURPOSE:
    	Provide a easy to zoom display of image data and to evaluate values.
             Initial version is only for images with uniform pixels
             (Type 1 field structures with DX, DY > 0.0)
           Note: All inputs are the same as the PLOTFLD command.  See PLOTFLD
                 for more details.  
           
    
     CATEGORY:
    	Graphics 
    
     CALLING SEQUENCE:
    
    	ZOOMS, STR
    
     INPUTS:
    
           STR:      Structure array number or a 2D field structure.
                     Note: SLICE can be used to generate a 2D structure.
                     If this is not a single block structure, it will be plotted 
                     in a pixmap and the interpolated, single block values
                     used in zooms.
    
     KEYWORD PARAMETERS:
          Maxzoom:   Maximum ZOOM parameter in one dimension
                     Default: MAXZOOM = max(MAX_ZOOM_DEFAULT , min([NX, NY])/8)
                       where NX and NY are the number of pixels in X and Y.
          MAGNIFICATION: Final magnification.  If there is a value on input
                     between 1 and MaxZoom, this value will be the initial 
                     maginification.  Default = 2
                     Note:  MAGNIFICATION will caused result in an equal number
                            of pixels in the X and Y direction.
                     Size of zoom image in pixels will be NX/magnification where NX
                       is the number of pixels in the X direction.
          XZoomrange: Final value of XRANGE; can be used with PLOTSTR to plot other 
                     data with the same abscissa values.  If there is a value
                     on input, it will be used as the center of the initial
                     magnification.  (More than one value will be averaged.)
                     Default = Image X-Midpoint
                     Note: Change in XZOOMRANGE must be greater than 0.08*DX
          YZoomrange: Final value of YRANGE; can be used with PLOTSTR to plot other 
                     data with the same abscissa values.  If there is a value
                     on input, it will be used as the center of the initial
                     magnification.  (More than one value will be averaged.)
                     Default = Image Y-Midpoint
                     Note: Change in YZOOMRANGE must be greater than 0.08*DY
           X/Ysize:  Size of windows, Default is set by Dualsize
                     Minimum window size is 100 x 100
                     (See SET_DRAWSIZE in PFIDL.)
           THERMOMETER:  By default, Thermometer is set.
                     Right Image: THERMOMETER ={ystyle:1}
                     Left Image: THERMOMETER ={ystyle:1}
           ASPECT:   Preserve the aspect ratio.
                     Default: ASPECT = 1 unless DX/DY > 10 or < 0.1
           PIXPLOT:  If set, PIXPLOT will be sent to plotstr
                     NOTE: Keyword PIXELS.  Four (4) characters are required.
         
     *** Returned Values ***
           X/YCursor: These values are set with the right mouse button.
                      Values can be deleted using the delete button.  
                      Designated points are shown in the right ZOOM window.
                      If WIDTH is greater than 1 then X and Y are centered in
                      a pixel.
                      If NPOINT = 0, then XCURSOR = YCURSOR = -999
           NPOINT:   Number of Xcursor and Ycursor values
           VALUE:    Value of the field/image at the points [Xcursor, Ycursor]
                     averaged over an areas of width WIDTH.
                     If width is greater than 1, then the location is the center
                       of a pixel and the sum of the pixels equal to WIDTH in each
                       direction is totaled in determining VALUE
                     If width is equal to 1 then the exact location is used and 
                       VALUE is determined by interpolation to the 4 nearest neighbors.
           WIDTH:    Array of WIDTH values for each VALUE
                     If WIDTH is input with a single value, it will be used as the 
                     initial width.  WIDTH is returned in pixel units; it will be rounded
                     to an odd number of pixels.  The display is in log10(pixels)
                     Default: width = 0.005 * minimum([nx, ny]) > 3
                     where nx and ny are the number of pixels in each direction.
                     Maximum width is 0.25*minimum([nx, ny]) 
               NOTE: WIDTH must be a variable if a value is to be returned.
               Note: Alog10(1) = 0.000000
                     Alog10(3) = 0.477121
                     Alog10(5) = 0.698970
                     Alog10(7) = 0.845098
                     Alog10(9) = 0.954243
                      etc
           PIXELS:   Used only on input.  If set, WIDTH is in pixels.
                     On output, WIDTH is in pixel units.  (DX and DY may be
                     unequal, but the average is over a square region in 
                     pixel units.
           SDEVIATION: Area weighted standard deviation for each VALUE
                     MOMENT is used to calculate average and standard deviation
                       for WIDTH > 1
                     SDeviation = weighted standard deviation for WIDTH = 1
                       that is: If VALUE = total(F*V) where F is a weight
                                and V are the values at the corner of the 
                                4 nearest values, then 
                                SDEVIATION=sqrt(total(F*(V-Value)^2)
    
             Note: The following 3 keywords are processed in the following 
                   order: UNSET, SetDefault, ShowDefault
    
           Unset      : Set Cursor and Maxzoom to their default values.
                        Xsize and Ysize must be set using explicit values in
                        ZOOMS or Set_DrawSize
                        Defaults values which are set are:
                                 Cursor  = 1
                                 MaxZoom = 100
                                 Xsize   = Dualsize[0]
                                 Ysize   = Dualsize[1]
           SetDefault : Use to set the default value of Cursor, Maxzoom, Xsize
                        and Ysize
                      Note: Values in Dualsize will be changed if Xsize and Ysize
                            are set.
           Showdefault: Show current default values
    
          All other keyword parameters are the same as PLO except the following
               which are set specifically for part or all of the ZOOMS command.
           Header:   Used for the plot header; set to 0 for the zoom image
           XSTYLE:   Set to 1 by default for all images.
           YSTYLE:   Set to 1 by default for all images. 
           INSTRUCTIONS:  Puts up an instruction widget.
           INSTR_OFFSET:  Location for the instruction widget
                          Default OFFSET = 0.5*[Xsize, Ysize]
     Procedure:
           Sliders allow the center point and the magnification to be set.
           The center point can be set by clicking on the original image
           The desired values are selected by right clinks in the zoom image or 
             by setting the value in the field widget.
           When the cursor is in the right window, the cursor position is displayed.
              A LEFT button press will center the right window on that X-Y value.
              A RIGHT button press will save the point into the keyword
                parameters: Xcursor and Ycursor with the values and standard deviation.
              VALUE will be determined by averaging a region of the image equal to 
                the specified SPOT size.
    
     EXAMPLE:
           Examine the details of the data in wdf array 3.
             ZOOMS, 3
    
           Compare arrays 2, 3, 4, and 5 in detail, put the legend at relative
             positions of [0.5, 0.5]
             ZOOMS, 2, 4, /ov, leg =[.5, .5]
    
     MODIFICATION HISTORY:
     	Written by:       Paul Mix, April 8, 2004
    

    (See ../pfidl/pfidl_2d/zooms.pro)