This page was created by the IDL library routine mk_html_help2.

Last modified: Sat Sep 20 09:22:05 2003.

general/science/

• 3D_STRUCTURE
  Documentation for the 3d structure.
• ADD_BDIR
  Adds magnetic field direction [theta,phi] to a 3d structure
• C_3D
  Returns the sum of the counts in temp.data
• CAL_BSN2
  Function returns a structure that describes the interaction of a B-field
• CONV_UNITS
• CONVERT_PH_UNITS
  Converts the units of the data array of ph data structures.
• CONVERT_VFRAME
• TRANSFORM_VELOCITY
• DIAG_P
  Returns the temperature: [Tpara,Tperp,Tperp], and
• EDIT3DBINS
• GET_3DT
  To generate time series data for "tplot"
• GET_BSN2
  Generates tplot structures for intersection of Bow Shock and s/c B-field line.
• GET_SYMM
• HEATFLUX
• J_3D
  Returns the flux, [Jx,Jy,Jz], 1/(cm^2-s)
• JE_3D
  Returns the energy flux, [Je_x,Je_y,Je_z], ergs/(cm^2-s)
• MAKE_3DMAP
  Returns a 3d map using the theta's and phi's of a 3d structure.
• MAT_DIAG
  Diagonalize a 3x3 symmetric matrix
• N_3D
  Returns the density, n, 1/cm^3
• OMNI3D
• P_3D
  Returns the pressure tensor, [Pxx,Pyy,Pzz,Pxy,Pxz,Pyz], eV/cm^3
• PAD
• PADPLOT
• PANGLE
  Computes pitch angle given two sets of theta and phi
• PLOT3D
  Draws a series of 3d color plots, one plot per energy step.
• PLOT3D_COM
• PLOT3D_OPTIONS
• PLOT_MAP
• PRESTENS
• SMOOTH_PERIODIC
• ENLARGE_PERIODIC
• SPEC3D
• SPHERE_TO_CART
• SUB3D
• SUM3D
• SYMM3D
• SYMMETRY_DIR
• T_3D
  Returns the temperature, [Tx,Ty,Tz,Tavg], eV
• UNITS
• V_3D
  Returns the velocity, [Vx,Vy,Vz], km/s
• VTH_3D
  Returns the thermal velocity, [Vthx,Vthy,Vthz,Vthavg], km/s
• XYZ_TO_POLAR
  

Routine Descriptions

NAME:
   3d_structure
PURPOSE: 
   Documentation for the 3d structure.
   This is NOT a procedure or a function. It is ONLY Documentation. don't
   try to run it!
   The 3d structure is the standard structure that contains all information
   necessary to do data analysis on a particle distribution function.
   The following is an example structure obtained from the WIND data set:

** Structure <1b689b0>, 29 tags, length=35304, refs=1:
   PROJECT_NAME    STRING    'Wind 3D Plasma'
   DATA_NAME       STRING    'Eesa Low'
   UNITS_NAME      STRING    'Counts'           Current Units.
   TIME            DOUBLE       8.2313292e+08   Sample start. Secs since 1970
   END_TIME        DOUBLE       8.2313292e+08   Sample End. Secs since 1970.
   INTEG_T         DOUBLE           3.0000000   Integration Time.  Seconds.
   NBINS           INT             88           number of angle bins.
   NENERGY         INT             15           number of energy bins.
   MAP             INT       Array(32, 32)      bin map (req'd only for plot3d)
   DATA            FLOAT     Array(15, 88)
   ENERGY          FLOAT     Array(15, 88)
   THETA           FLOAT     Array(15, 88)
   PHI             FLOAT     Array(15, 88)
   GEOM            FLOAT     Array(15, 88)      Req'd by convert_esa_units
   DENERGY         FLOAT     Array(15, 88)
   DTHETA          FLOAT     Array(15, 88)
   DPHI            FLOAT     Array(15, 88)
   DOMEGA          FLOAT     Array(15, 88)
   EFF             FLOAT     Array(15, 88)      Req'd by convert_esa_units
   FEFF            FLOAT     Array(15, 88)      Req'd by convert_esa_units 
   MASS            DOUBLE       5.6856593e-06
   GEOMFACTOR      DOUBLE       0.00039375000   Req'd by convert_esa_units
   VALID           LONG                 1
   SPIN            LONG             17152       (Optional)
   UNITS_PROCEDURE STRING    'convert_esa_units'
   MAGF            FLOAT     Array(3)           (Optional magnetic field vec.)
   VSW             FLOAT     Array(3)           (Optional flow velocity vec.)


The following functions will return a 3d structure:

  For the WIND data set:            ("LOAD_3DP_DATA" must be called first.)
    "GET_EL", "GET_PL","GET_EH","GET_PH","GET_PLB","GET_PHB","GET_ELB",
    "GET_EHS","GET_SF","GET_SO","GET_SFB","GET_SOB"

  For the GIOTTO data set:
    "GET_GI"

  For the CLUSTER data set:
    In Progress....

  For the FAST data set:
    In Progress....

Once the 3d structure is obtained then it can be displayed with the following
routines:
    "SPEC3D", "PLOT3D", "CONT3D"

The following routines are useful for manipulating the data:
    "CONV_UNITS", "CONVERT_VFRAME", "PAD"

(See 3d_structure.pro)

PROCEDURE:  add_bdir,dat,source
PURPOSE:
    Adds magnetic field direction [theta,phi] to a 3d structure
    The new structure element will be a two element vector [theta,phi]
    with the tag name 'bdir'.
INPUT:
    dat:   3D data structure        (i.e. from 'GET_EL')
    [source] : String index that points to magnetic field data.
Notes:
    	Magnetic field data must be loaded first.  
	See 'GET_MFI'

(See add_bdir.pro)

FUNCTION:	cal_bsn2(sx,sy,sz,bx,by,bz,vmag,bow=bow)
INPUT:
	sx,sy,sz:	x, y, and z coodinates of spacecraft in GSE with
			units of Re
	bx,by,bz:	magnetic field direction
OPTIONS:
	bow:	structure containing {L,ecc,x0}
		L:	standoff parameter with units of Re
		ecc:	eccentricity of shock
		x0:	focus location in Re

       hyperbolic bow shock, see JGR 1981, p.11401, Slavin Fig.7
       r = L/(1+ecc*cos(theta))
       1 = (x-x0-c)^2/a^2 - (y^2+z^2)/b^2
       default L = b^2/a = 23.5
               ecc = c/a = 1.15
               xoffset= 3
               c = (a^2 + b^2)^.5 = L*e/(e^2-1) = 83.8
               a = L/(e^2-1) = 72.87
               b = L/(e^2-1)^.5 = 41.38
PURPOSE:
	Function returns a structure that describes the interaction of a B-field
	with a hyperboloid bow shock model.
	Returned structure elements include:
		th_bn: the angle (in degrees) between shock normal and the
			field line that passes through the spacecraft
		l1: the distance along the field line to the shock
		l2: the distance from a point that is missdist from the
			spacecraft in x to the tangent point
		d,m: the distance along x from the spacecraft to a point
			where the B field line would be tangent to the
			bow shock.  A postive d means that the field
			line has already intersected the shock.  A positive
			m indicates that the field line has not yet
			intersected the shock.
		intpos: position vector in GSE of point where field line
			originating at spacecraft intersects bow shock
	All distances are in Re.
CREATED BY:
	P. Schroeder
LAST MODIFICATION: 
       L. Winslow 9/15/00
LAST MODIFICATION: %W% %E%

(See cal_bsn2.pro)

NAME:      convert_ph_units
PURPOSE:            
           Converts the units of the data array of ph data structures.
CALLING SEQUENCE:      convert_ph_units,data,units
INPUTS:    data:  a ph data structure returned by "get_ph1.pro" or "GET_PH2.pro"
                  data.data is rescaled in the requested units, and
                  data.units is set to the name of the new units
           units: a string.  One of: 'COUNTS','RATE','EFLUX','FLUX','DF'

KEYWORD PARAMETERS:    
           DEADTIME: (double) specifies a deadtime: the interval during which 
                     a channel plate detector is turned off to record an event.
                     data.deadtime defaults to 1e-6 
		      (and has precedence over deadtime)
COMMON BLOCKS:   get_ph_com: contains one element: deadtime

LAST MODIFICATION:     @(#)convert_ph_units.pro	1.1 97/04/21
CREATED BY:            Frank Marcoline.  Patterened after other convert_*_units.pro procedures.

(See convert_ph_units.pro)

NAME:	
	convert_vframe

FUNCTION:  convert_vframe ,  dat,  velocity
PURPOSE:   Change velocity frames 
INPUT: 
  dat: 3d data structure
  velocity: SW velocity vector  [VX,VY,VZ]
OUTPUT:  3d data structure.  Data will be in a different coordinate frame.
    (data will also be in units of distrubution function.)
KEYWORDS:
   ETHRESH:  Threshold energy for interpolation.
   BINS:     Angle bins to be used
   EVALUES:
   INTERPOLATE:  set to non-zero value to have the data evaluated 
   (interpolated) at the original energy steps.

CREATED BY:	Davin Larson
LAST MODIFICATION:	@(#)convert_vframe.pro	1.21 02/11/01

(See convert_vframe.pro)

FUNCTION:	conv_units

PURPOSE:	To convert from counts to any other unit which is supported.
		This procedure is just a shell that calls whatever conversion
		procedure is specified in data.units_procedure.
		right now the only conversion procedures are
		"convert_esa_units" and
		"CONVERT_SST_UNITS" 
INPUT:		
	data:	A 3d data structure such as those generated by get_el, get_eh,
		get_pl,get_ph,etc.
		e.g. "GET_EL"
	units:	The units you wish to convert to, such as eflux,flux,df,ncounts,
		rate,nrate.
KEYWORDS:	
	scale:	a dummy keyword, returns the scale used to convert.

CREATED BY:	Davin Larson
LAST MODIFICATION: 	@(#)conv_units.pro	1.8 95/11/07

(See conv_units.pro)

FUNCTION:	c_3d(dat,ENERGY=en,ERANGE=er,EBINS=ebins,ANGLE=an,ARANGE=ar,BINS=bins)
INPUT:	
	dat:	structure,	2d data structure filled by get_eesa_surv, get_eesa_burst, etc.
KEYWORDS
	ENERGY:	fltarr(2),	optional, min,max energy range for integration
	ERANGE:	fltarr(2),	optional, min,max energy bin numbers for integration
	EBINS:	bytarr(na),	optional, energy bins array for integration
					0,1=exclude,include,  
					na = dat.nenergy
	ANGLE:	fltarr(2,2),	optional, angle range for integration
				theta min,max (0,0),(1,0) -90GET_3DT" to generate 
	time series data for "TPLOT".

CREATED BY:
	J.McFadden	95-7-27	
LAST MODIFICATION:
	96-7-6		J.McFadden

(See c_3d.pro)

Procedure:	diag_p, p, n, t=t, s=s
INPUT:	
	p:	pressure array of n by 6 or a string (e.g., 'p_3d_el')
	n:	density array of n or a string (e.g., 'n_3d_el')
PURPOSE:
	Returns the temperature: [Tpara,Tperp,Tperp], and 
		the unit symmetry axis s. Also returns 'T_diag' and 'S.axis'
		for plotting purposes.  

CREATED BY:
	Tai Phan	95-09-28
LAST MODIFICATION:
	95-9-29		Tai Phan

(See diag_p.pro)

PROCEDURE:  edit3dbins,dat,bins
PURPOSE:   Interactive procedure to produce a bin array for selectively 
    turning angle bins on and off.  Works on a 3d structure (see 
    "3D_STRUCTURE" for more info)

INPUT:
   dat:  3d data structure.  (will not be altered)
   bins:  a named variable in which to return the results.
KEYWORDS:
   EBINS:     Specifies energy bins to plot.
   SUM_EBINS: Specifies how many bins to sum, starting with EBINS.  If
              SUM_EBINS is a scaler, that number of bins is summed for
              each bin in EBINS.  If SUM_EBINS is an array, then each
              array element will hold the number of bins to sum starting
              at each bin in EBINS.  In the array case, EBINS and SUM_EBINS
              must have the same number of elements.
SEE ALSO:  "PLOT3D" and "PLOT3D_OPTIONS"
CREATED BY:	Davin Larson
FILE: edit3dbins.pro
VERSION:  1.14
LAST MODIFICATION: 98/01/16

(See edit3dbins.pro)

NAME:
	enlarge_periodic
FUNCTION:   enlarge_periodic
INPUT:   image   (On the surface of a sphere)
PURPOSE: enlarges a 2 dimensional matrix by n elements on each side
   It assumes the array has spherical boundary conditions.
OUTPUT:  enlarged image array
NOTES:   Called from function: 'SMOOTH_PERIODIC'

CREATED BY:	Davin Larson
LAST MODIFICATION:	@(#)smooth_periodic.pro	1.5 95/10/04

(See smooth_periodic.pro)

PROGRAM:	get_3dt(funct,get_dat,ERANGE=erange,BINS=bins,NAME=name)
INPUT:	
	funct:	function,	function that operates on structures generated 
					by get_pl, get_el, etc.
				e.g. "GET_EL"

				funct   = 'n_3d','j_3d','v_3d','p_3d','t_3d',
					  'vth_3d', or 'c_3d'
				"N_3D"
				"J_3D"
				"V_3D"
				"P_3D"
				"T_3D"
				"VTH_3D"
				"C_3D"
	get_dat:function,	function that returns 3d data structures
				function name must be "get_"+"get_dat"  
				get_dat = 'pl' for get_pl, 
				get_dat = 'el' for get_el, etc.
KEYWORDS:
	erange:	fltarr(2),	optional, min,max energy bin numbers for integration
	bins:	bytarr(nbins),	optional, angle bins for integration, see edit3dbins.pro
				0,1=exclude,include,  nbins = temp.nbins
	name:	string		New name of the Data Quantity
				Default: funct+'_'+get_dat
       times:  dblarr(1or2)or  Specifies start time (and end time)
               strarr(1or2)   
       index:  lonarr(1 or 2)  Specifies starting index (and ending index)
                               keyword time overrides keyword index
PURPOSE:
	To generate time series data for "TPLOT" 
NOTES:	
	Program names time series data to funct+"_"+get_dat.
		See "TPLOT_NAMES".

CREATED BY:    J.McFadden
LAST MODIFICATION:  01/05/09
FILE:   @(#)get_3dt.pro	1.13

(See get_3dt.pro)

PROGRAM:	get_bsn2,PNAME=pname,BNAME=bname,VNAME=vname,BOW=bow,
			intpos=intpos

INPUT OPTIONS 
	pname:	string,		Name of orbital position structure
				Default is 'wi_pos'
	bname:	string,		Name of magnetic field structure  
				Default is 'wi_B3'
	vname:  string,		Name of solar wind velocity structure
				Default is 'wi_pm_Vp'
	bow:	structure	Bow Shock parameters
				Default bow={standoff:23.5,eccentricity:1.15,x_offset:3.0}
PURPOSE:
	Generates tplot structures for intersection of Bow Shock and s/c B-field line.
	Generates the following structures:
               th_bn: the angle (in degrees) between shock normal and the
                       field line that passes through the spacecraft
               l1: the distance along the field line to the shock
               l2: the distance from a point that is missdist from the
                       spacecraft in x to the tangent point
               d,m: the distance along x from the spacecraft to a point
                       where the B field line would be tangent to the
                       bow shock.  A positive d means that the field
                       line has already intersected the shock.  A positive
			m indicates that the field line has not yet intersected
                       the shock.
       All distances are in Re. l1 and l2 are negative if the field line is
	anti-parallel to the vector connecting the spacecraft and the point
	of field line intersection.
OPTIONAL OUTPUT:
	intpos:	array of position vectors giving points where bow shock
		intersects B field line that passes through spacecraft
CREATED BY:
	P.Schroeder
LAST MODIFICATION:
	@(#)get_bsn2.pro	1.5 02/04/17

(See get_bsn2.pro)

PROCEDURE:	get_symm
PURPOSE:	Gets symmetry direction of magnetic field
INPUT:
	none
KEYWORDS:
	use_mag:
	use_q:
	use_dir:
	time:
	stheta:
	sphi:

CREATED BY: 	Davin Larson
LAST MODIFICATION:	@(#)get_symm.pro	1.5 95/08/24

(See get_symm.pro)

FUNCTION:	heatflux
PURPOSE:	Calulates heatlux from a 3dimensional data structure such as
		those generated by get_el,get_pl,etc. 
		e.g. "GET_EL"
INPUT:		
	dat:	A 3d data structure.
KEYWORDS:
	esteprange:	the energy step range to use, default is full range
CREATED BY:	Davin Larson
LAST MODIFICATION:	@(#)heatflux.pro	1.5 95/10/06

(See heatflux.pro)

FUNCTION:	je_3d(dat,ENERGY=en,ERANGE=er,EBINS=ebins,ANGLE=an,ARANGE=ar,BINS=bins)
INPUT:	
	dat:	structure,	2d data structure filled by get_eesa_surv, get_eesa_burst, etc.
KEYWORDS
	ENERGY:	fltarr(2),	optional, min,max energy range for integration
	ERANGE:	fltarr(2),	optional, min,max energy bin numbers for integration
	EBINS:	bytarr(na),	optional, energy bins array for integration
					0,1=exclude,include,  
					na = dat.nenergy
	ANGLE:	fltarr(2,2),	optional, angle range for integration
				theta min,max (0,0),(1,0) -90GET_3DT" or "get_2dt" to
	generate time series data for "TPLOT.pro".

CREATED BY:
	J.McFadden	97-12-4
LAST MODIFICATION:
	97-12-4		J.McFadden

(See je_3d.pro)

FUNCTION:	j_3d(dat,ENERGY=en,ERANGE=er,EBINS=ebins,ANGLE=an,ARANGE=ar,BINS=bins)
INPUT:	
	dat:	structure,	2d data structure filled by get_eesa_surv, get_eesa_burst, etc.
KEYWORDS
	ENERGY:	fltarr(2),	optional, min,max energy range for integration
	ERANGE:	fltarr(2),	optional, min,max energy bin numbers for integration
	EBINS:	bytarr(na),	optional, energy bins array for integration
					0,1=exclude,include,  
					na = dat.nenergy
	ANGLE:	fltarr(2,2),	optional, angle range for integration
				theta min,max (0,0),(1,0) -90GET_3DT" or "get_2dt" to
	generate time series data for "TPLOT.pro".

CREATED BY:
	J.McFadden	95-7-27
LAST MODIFICATION:
	96-7-6		J.McFadden

(See j_3d.pro)

FUNCTION make_3dmap, dat,nx,ny
PURPOSE:
  Returns a 3d map using the theta's and phi's of a 3d structure.
  This routine is primarily used by "PLOT3D".
INPUT:  dat:  a 3d structure (see "3D_STRUCTURE" for more info).
         nx:  x dimension of output array.
         ny:  y dimension of output array.
OUTPUT: A 2 dimensional array of bin values that reflect the mapping.
KEYWORDS: 
   HIGHEST:  force the highest bin number to prevail for overlapping bins.
ASSUMPTIONS: theta +/- dtheta should be in the range:  -90 to +90.
NOTES: if there are any overlapping bins, then the lowest bin number
    will win, unless the HIGHEST keyword is set.
WRITTEN BY:  Davin Larson,   96-2-8
LAST MODIFICATION:	@(#)make_3dmap.pro	1.7 99/10/22

(See make_3dmap.pro)

Program:	mat_diag, p, EIG_VAL= eig_val, EIG_VEC= eig_vec
INPUT:	
	p	6-element vector [Pxx, Pyy, Pzz, Pxy, Pxz, Pyz] of a
		symmetric matrix
OUTPUT:
	eig_val, eig_vec
PURPOSE:
	Diagonalize a 3x3 symmetric matrix
	Returns the eigenvalues and eigenvectors.
	The eigenvalues are the diagnonal elements of the matrix
	The eigenvectors are the associated principle axis. 
NOTES:	
	The first eigenvalue (eig_val(0)) and eigenvector (eig_vec(*,0))
	are the distinguisheable eigenvalue and the major (symmetry) axis,
	respectively.  
	The "degenerate" eigenvalues are sorted such that the 2nd eigenvalue
	is smaller than the third one.
CREATED BY:
	Tai Phan (95-9-15)
LAST MODIFICATION:
	95-9-29		Tai Phan

(See mat_diag.pro)

FUNCTION:	n_3d(dat,ENERGY=en,ERANGE=er,EBINS=ebins,ANGLE=an,ARANGE=ar,BINS=bins)
INPUT:	
	dat:	structure,	2d data structure filled by get_eesa_surv, get_eesa_burst, etc.
KEYWORDS
	ENERGY:	fltarr(2),	optional, min,max energy range for integration
	ERANGE:	fltarr(2),	optional, min,max energy bin numbers for integration
	EBINS:	bytarr(na),	optional, energy bins array for integration
					0,1=exclude,include,  
					na = dat.nenergy
	ANGLE:	fltarr(2,2),	optional, angle range for integration
				theta min,max (0,0),(1,0) -90GET_3DT" or "get_2dt" to 
	generate time series data for "TPLOT.pro".

CREATED BY:
	J.McFadden	95-7-27	
LAST MODIFICATION:
	96-7-6		J.McFadden	added more keywords

(See n_3d.pro)

FUNCTION:  omni3d
PURPOSE:  produces an omnidirectional spectrum structure by summing
 over the non-zero bins in the keyword bins.
 this structure can be plotted with "SPEC3D"

CREATED BY:	Davin Larson
LAST MODIFICATION:	@(#)omni3d.pro	1.12 02/04/17

 WARNING:  This is a very crude structure; use at your own risk.

(See omni3d.pro)

FUNCTION:	pad
PURPOSE:	makes a data pad from a 3d structure
INPUT:	
	dat:	A 3d data structure such as those gotten from get_el,get_pl,etc.
		e.g. "GET_EL"
KEYWORDS:
	bdir:	Add B direction
	esteps:	Energy steps to use
	bins:	bins to sum over
	num_pa:	number of the pad

CREATED BY:	Davin Larson
LAST MODIFICATION:	@(#)pad.pro	1.21 02/04/17

(See pad.pro)

PROCEDURE: padplot,pad
   Plots pad data vs pitch angle.
INPUTS:
   pad   - structure containing pitch angle distribution (PAD) data. 
           (Obtained from "PAD()" routine)
KEYWORDS:
   LIMITS - limit structure. (see "XLIM" , "YLIM" or "TPLOT/help_list.html#OPTIONS">OPTIONS")
      The limit structure can have the following elements:
      UNITS:  units to be plotted in.
      ALL PLOT and OPLOT keywords.
   UNITS  - convert to given data units before plotting
   MULTI  - Set to the number of plots desired across the page.
   OPLOT  - Overplots last plot if set.
   LABEL  - set to print labels for each energy step.

SEE ALSO:	"SPEC3D"

CREATED BY:	Davin Larson
LAST MODIFICATION:	@(#)padplot.pro	1.18 02/04/17

(See padplot.pro)

FUNCTION:  pangle,theta,phi,b_theta,b_phi
PURPOSE:
 Computes pitch angle given two sets of theta and phi
INPUT:
  theta,phi:       double (array or scaler)  first directions
  b_theta,b_phi :  double (array or scaler)  second directions
RETURNS:  pitch angle (array or scaler) same dimensions as theta and phi

CREATED BY:	Davin Larson
LAST MODIFICATION:	@(#)pangle.pro	1.4 95/11/28

(See pangle.pro)

NAME:
  PLOT3D
PROCEDURE: plot3d, dat , latitude, longitude
PURPOSE:  
  Draws a series of 3d color plots, one plot per energy step.
INPUT:
  dat:  3d data structure.
  latitude:  latitude of center of plot
  longitude:  longitude of center of plot
KEYWORDS:
   EBINS:     Specifies energy bins to plot.
   SUM_EBINS: Specifies how many bins to sum, starting with EBINS.  If
              SUM_EBINS is a scaler, that number of bins is summed for
              each bin in EBINS.  If SUM_EBINS is an array, then each
              array element will hold the number of bins to sum starting
              at each bin in EBINS.  In the array case, EBINS and SUM_EBINS
              must have the same number of elements.
   BNCENTER:  if > 0 then lat,lon set so that B direction is in center
              if < 0 then lat,lon set so that -B direction is in center
              ('magf' element must exist in dat structure. See "ADD_MAGF")
   BINS:    bins to use for autoscaling.
   SMOOTH:  smoothing parameter.  0=none,  2 is typical
   TITLE:   overrides default plot title.
   NOTITLE: if set, suppresses plot title.
   NOCOLORBAR: if set, suppresses colorbar.
   NOBORDER: if set, suppresses plot border.
SEE ALSO:  "PLOT3D_OPTIONS" to see how to set other options.

CREATED BY:	Davin Larson
LAST MODIFICATION:	@(#)plot3d.pro	1.43 02/04/17

(See plot3d.pro)

COMMON BLOCK:	plot3d_com
PURPOSE:	Common block for "PLOT#D" routines
CREATED BY:	Davin Larson
LAST MODIFICATION:	@(#)plot3d_com.pro	1.8 95/11/07
SEE ALSO:   "PLOT3D" and "PLOT3D_OPTIONS"

(See plot3d_com.pro)

PROCEDURE:  plot3d_options
PURPOSE:  Sets default TPLOT/help_list.html#OPTIONS">OPTIONS for the "PLOT3D" routine
   The only inputs are through keywords:
KEYWORDS:
   MAP:  one of the following strings: 
       'cylindrical', 'molleweide', 'ait' ,'lambert'  .... 
       (See manual for other maps, only the first 3 characters are req'd)
   COMPRESS:  integer defining map resolution (see manual)  1 si default
   SMOOTH:    0 gives no smoothing.
   LOG:       0: linear color scale;   1: log color scale
   TRIANGULATE:  Uses spherical triangulation if set
   LATITUDE:  Center Latitude.
   LONGITUDE: Center Longitude.

CREATED BY:	Davin Larson
LAST MODIFICATION:	@(#)plot3d_options.pro	1.10 96/09/24

(See plot3d_options.pro)

 PROCEDURE:
	PLOT_MAP

 DESCRIPTION:

	Plot the map from the standard 3-D data structure that is returned
	from the IDL from SDT interface.  The THETA, PHI, DTHETA, DPHI,
	DATA_NAME and PROJECT_NAME tags must exist for this routine to work.  
	(The standard 3-D data structure should contain these.)

	
 CALLING SEQUENCE:

 	plot_map, data_structure

 ARGUMENTS:

	data_structure 		The standard 3-D data structure to plot the
				map from.

 REVISION HISTORY:

	@(#)plot_map.pro	1.1 22 Aug 1995
 	Originally written by Jonathan M. Loran,  University of 
 	California at Berkeley, Space Sciences Lab.   Aug. '95

(See plot_map.pro)

PROCEDURE:	prestens
PURPOSE:	This function computes the relative components of the pressure
		tensor
INPUT:	
	dat:	A 3d structure such as those gotten by using get_el,get_pl,etc.
		e.g. "GET_EL"
KEYWORDS:	
	esteprange:	energy range to use

CREATED BY:	Davin Larson
LAST MODIFICATION:	@(#)prestens.pro	1.5 95/10/06

NOTE:	 It is NOT yet corrected to give physical results

(See prestens.pro)

FUNCTION:	p_3d(dat,ENERGY=en,ERANGE=er,EBINS=ebins,ANGLE=an,ARANGE=ar,BINS=bins)
INPUT:	
	dat:	structure,	2d data structure filled by get_eesa_surv, get_eesa_burst, etc.
KEYWORDS
	ENERGY:	fltarr(2),	optional, min,max energy range for integration
	ERANGE:	fltarr(2),	optional, min,max energy bin numbers for integration
	EBINS:	bytarr(na),	optional, energy bins array for integration
					0,1=exclude,include,  
					na = dat.nenergy
	ANGLE:	fltarr(2,2),	optional, angle range for integration
				theta min,max (0,0),(1,0) -90GET_3DT" or "get_2dt" to
	generate time series data for "TPLOT.pro".

CREATED BY:
	J.McFadden	95-7-27
LAST MODIFICATION:
	96-7-6		J.McFadden

(See p_3d.pro)

NAME:
	smooth_periodic

FUNCTION: smooth_periodic, old_image, n
PURPOSE:  Uses box car smoothing of a surface with sperical periodic boundary
    conditions.
INPUT:
   old_image:  2d matrix
   n:          size of boxcar averaging window
Output:  smoothed image.

CREATED BY:	Davin Larson
LAST MODIFICATION:	@(#)smooth_periodic.pro	1.5 95/10/04

(See smooth_periodic.pro)

PROCEDURE: spec3d,data
   Plots 3d data as energy spectra.
INPUTS:
   data   - structure containing 3d data  (obtained from get_??() routine)
		e.g. "GET_EL"
KEYWORDS:
   LIMITS - A structure containing limits and display options.
             see: "TPLOT/help_list.html#OPTIONS">OPTIONS", "XLIM" and "YLIM", to change limits
   UNITS  - convert to given data units before plotting
   COLOR  - array of colors to be used for each bin
   BINS   - array of bins to be plotted  (see "EDIT3DBINS" to change)
   OVERPLOT  - Overplots last plot if set.
   LABEL  - Puts bin labels on the plot if set.

See "PLOT3D" for another means of plotting data.
See "CONV_UNITS" to change units.
See "TIME_STAMP" to turn time stamping on and off.


CREATED BY:	Davin Larson  June 1995
FILE:  spec3d.pro
VERSION 1.25
LAST MODIFICATION: 02/04/17

(See spec3d.pro)

PROCEDURE sphere_to_cart,r,theta,phi, x,y,z
PURPOSE:  transform from spherical to cartesian coordinates
INPUTS:  r, theta, phi    (array or scaler)
OUTPUTS: x, y, z          (will have the same dimensions as r,theta,phi)
KEYWORD OUTPUT:
   VEC:  a named variable in which the vector [x,y,z] is returned

CREATED BY:	Davin Larson
LAST MODIFICATION:	@(#)sphere_to_cart.pro	1.6 02/11/01

NOTES:
   -90 < theta < 90   (latitude not co-lat)  

(See sphere_to_cart.pro)

FUNCTION: sub3d
PURPOSE: Takes two 3D structures and returns a single 3D structure
  whose data is the difference of the two.
  This routine is useful for subtracting background counts.
  Integration period is considered if units are in counts.
INPUTS: d1,d2  each must be 3D structures obtained from the get_?? routines
	e.g. "GET_EL"
RETURNS: single 3D structure

CREATED BY:	Davin Larson
LAST MODIFICATION:	@(#)sub3d.pro	1.10 01/10/08

Notes: This is a very crude subroutine. Use at your own risk.

(See sub3d.pro)

FUNCTION: sum3d
PURPOSE: Takes two 3D structures and returns a single 3D structure
  whose data is the sum of the two
INPUTS: d1,d2  each must be 3D structures obtained from the get_?? routines
	e.g. "GET_EL"
RETURNS: single 3D structure

CREATED BY:	Davin Larson
LAST MODIFICATION:	@(#)sum3d.pro	1.8 02/04/17

Notes: This is a very crude subroutine. Use at your own risk.

(See sum3d.pro)

FUNCTION:	symm3d
PURPOSE:	Returns [theta,phi]  given a 3d data struct
INPUT:
	dat:	A 3d data structure such as those generated by get_el,get_pl,etc
		e.g. "GET_EL"
KEYWORDS:
	esteps:		energy steps to use

CREATED BY:	Davin Larson
LAST MODIFICATION:	@(#)symm3d.pro	1.5 95/10/06

(See symm3d.pro)

FUNCTION:	symmetry_dir
PURPOSE:	Calculates symmetry direction
INPUT:
	Pt:	array of pts
KEYWORDS:
	none

CREATED BY:	Davin Larson
LAST MODIFICATION:	@(#)symmetry_dir.pro	1.3 95/08/24

(See symmetry_dir.pro)

NAME:	
	transform_velocity

PROCEDURE:   transform_velocity,  vel, theta, phi,  deltav
PURPOSE:  used by the convert_vframe routine to transform arrays of velocity
    thetas and phis by the offset deltav
INPUT:
  vel:  array of velocities
  theta: array of theta values
  phi:   array of phi values
  deltav: [vx,vy,vz]  (transformation velocity)
KEYWORDS:
	vx,vy,vz:	return vx,vy,vz separately as well as in vector form

CREATED BY:	Davin Larson
LAST MODIFICATION:	@(#)convert_vframe.pro	1.21 02/11/01

(See convert_vframe.pro)

FUNCTION:	t_3d(dat,ENERGY=en,ERANGE=er,EBINS=ebins,ANGLE=an,ARANGE=ar,BINS=bins)
INPUT:	
	dat:	structure,	2d data structure filled by get_eesa_surv, get_eesa_burst, etc.
KEYWORDS
	ENERGY:	fltarr(2),	optional, min,max energy range for integration
	ERANGE:	fltarr(2),	optional, min,max energy bin numbers for integration
	EBINS:	bytarr(na),	optional, energy bins array for integration
					0,1=exclude,include,  
					na = dat.nenergy
	ANGLE:	fltarr(2,2),	optional, angle range for integration
				theta min,max (0,0),(1,0) -90GET_3DT" or "get_2dt" to
	generate time series data for "TPLOT.pro".

CREATED BY:
	J.McFadden	95-7-27
LAST MODIFICATION:
	96-7-6		J.McFadden

(See t_3d.pro)

PROCEDURE:  units
PURPOSE:    adds the tag 'units' to the structure "struct"
INPUTS: 
   struct:  structure to be added to.  (Created if non-existent)
   units:     string containing units name.
Typical usage:
   units,lim,'Counts'

CREATED BY:	Davin Larson
LAST MODIFICATION: 	@(#)units.pro	1.4 02/04/17

(See units.pro)

FUNCTION:	vth_3d(dat,ENERGY=en,ERANGE=er,EBINS=ebins,ANGLE=an,ARANGE=ar,BINS=bins)
INPUT:	
	dat:	structure,	2d data structure filled by get_eesa_surv, get_eesa_burst, etc.
KEYWORDS
	ENERGY:	fltarr(2),	optional, min,max energy range for integration
	ERANGE:	fltarr(2),	optional, min,max energy bin numbers for integration
	EBINS:	bytarr(na),	optional, energy bins array for integration
					0,1=exclude,include,  
					na = dat.nenergy
	ANGLE:	fltarr(2,2),	optional, angle range for integration
				theta min,max (0,0),(1,0) -90GET_3DT" or "get_2dt" to
	generate time series data for "TPLOT.pro".

CREATED BY:
	J.McFadden	95-7-27
LAST MODIFICATION:
	96-7-6		J.McFadden

(See vth_3d.pro)

FUNCTION:	v_3d(dat,ENERGY=en,ERANGE=er,EBINS=ebins,ANGLE=an,ARANGE=ar,BINS=bins)
INPUT:	
	dat:	structure,	2d data structure filled by get_eesa_surv, get_eesa_burst, etc.
KEYWORDS
	ENERGY:	fltarr(2),	optional, min,max energy range for integration
	ERANGE:	fltarr(2),	optional, min,max energy bin numbers for integration
	EBINS:	bytarr(na),	optional, energy bins array for integration
					0,1=exclude,include,  
					na = dat.nenergy
	ANGLE:	fltarr(2,2),	optional, angle range for integration
				theta min,max (0,0),(1,0) -90GET_3DT" or "get_2dt" to
	generate time series data for "TPLOT.pro".

CREATED BY:
	J.McFadden	95-7-27	
LAST MODIFICATION:
	96-7-6		J.McFadden

(See v_3d.pro)

PROCEDURE:  xyz_to_polar,xyz
PURPOSE: Calculates magnitude, theta and phi given a 3 vector 
INPUT:   several options exist for xyz:
    string:    data associated with the string is used.
    structure: data.y is assumed to contain the xyz array
    array(n,3)   n by (x,y,z components)
    array(3)      vector:  [x,y,z]
RETURN VALUES: through the keywords.  Same dimensions and type as the 
    input value of x.
KEYWORDS:    Named variables in which results are put
   MAGNITUDE:
   THETA:
   PHI:   
   MAX_VALUE:
   MIN_VALUE:
   MISSING:
OPTION KEYWORDS:  These are used to set "CART_TO_SPHERE" opts.
   CO_LATITUDE:   If set theta will be in co-latitude. (0<=theta<=180)
   PH_0_360:      If set positive, 0<=phi<=360, if zero, -180<=phi<=180.
                  If set negative, will guess the best phi range.
   PH_HIST:       A 2 element vector, a min and max histeresis value.
EXAMPLES:

     Passing arrays:
x = findgen(100)
y = 2*x
z = x-20
vecs = [[x],[y],[z]]
xyz_to_polar,vecs,mag=mag      ;mag will be the magnitude of the array.

     Passing a structure:
dat = {ytitle:'Vector',x:findgen(100),y:vecs}
xyz_to_polar,dat,mag=mag,theta=th,phi=ph
mag,th and ph will be all be structures.

     Passing a string:  (see store_data, get_data)
xyz_to_polar,'Vp'   ; This assumes data has been created for this string.
    This will compute new data quantities: 'Vp_mag','Vp_th','Vp_ph'

(See xyz_to_polar.pro)