This page was created by the IDL library routine `mk_html_help2`.

Last modified: Tue Aug 5 18:17:40 2025.

# Directory Listing of Routines

# projects/themis/spacecraft/particles/slices/core

- THM_PART_SLICE1D_MULT
- THM_PART_SLICE1D_R
- THM_PART_SLICE1D_XY
- THM_PART_SLICE2D_2DI
- THM_PART_SLICE2D_3DI
- THM_PART_SLICE2D_CLIMIT
- THM_PART_SLICE2D_COLLATE
- THM_PART_SLICE2D_COTRANS
- THM_PART_SLICE2D_EBOUNDS
- THM_PART_SLICE2D_FAC
- THM_PART_SLICE2D_GEO
- THM_PART_SLICE2D_GETDATA
- THM_PART_SLICE2D_GETMAG
- THM_PART_SLICE2D_GETSPHERE
- THM_PART_SLICE2D_GETSUN
- THM_PART_SLICE2D_GETVEL
- THM_PART_SLICE2D_INTRANGE
- THM_PART_SLICE2D_NCOUNT
- THM_PART_SLICE2D_NN
- THM_PART_SLICE2D_OLD
- THM_PART_SLICE2D_ORIENTSLICE
- THM_PART_SLICE2D_REGRIDSPHERE
- THM_PART_SLICE2D_RLOG
- THM_PART_SLICE2D_ROTATE
- THM_PART_SLICE2D_S2C
- THM_PART_SLICE2D_SMOOTH
- THM_PART_SLICE2D_SUBTRACT
- THM_PART_SLICE_EXTRACT
- THM_UI_SLICE2D_BAR__DEFINE.PRO
  Object created for the 2d slices interface. Allows scrolling back

# Routine Descriptions

## THM_PART_SLICE1D_MULT

[Next Routine] [List of Routines]

    Important:
      This is an incomplete helper function and is still in development.

    Procedure:
      thm_part_slice1d_mult

    Purpose:
      Produce line plots from particle velocity slices along various orientations.

    Calling Sequence:
      thm_part_slice1d, slice, [,x=x | ,y=y | ,v=v | ,e=e ] [,angle=angle] [,data=data]

    Input:
         slice: slice structure from thm_part_slice2d
             x: values at which to align cut along the x axis (km/s)
             y: values at which to align cut along the y axis (km/s)
                (defaults to y=0 if x, y, v, e not set)
             v: values at which to align a radial cut (km/s)
             e: values at which to align a radial cut (eV)
         angle: value (degrees) to rotate the cut by if using x or y

    Graphis Keywords:
       -Any IDL graphics keywords that are valid for the "plot" and "oplot" procedure
        may also be used.

    Output:

    Notes:

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice1d_mult.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice1d_mult.pro)

## THM_PART_SLICE1D_R

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      thm_part_slice1d_r

    Purpose:
      Return the set of points at which a radial cut will be interpolated
      and corresponding plot labels.

    Calling Sequence:
      thm_part_slice1d_r, slice (vin=vin | ein=ein), xout=xout, yout=yout,
                          xaxis=xaxis, xtitle=xtitle

    Input:
      slice: 2D slice structure
      vin: velocity (km/s) at which to create cut
      ein: energy (eV) at which to create cut

    Output:
      xout: x coordinates of points to interpolate to
      yout: y coordinates of points to interpolate to
      xaxis: final plot's x axis (angle)
      xtitle: title for final plot's x axis
      error: flag, 1 if error 0 if not

    Notes:

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice1d_r.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice1d_r.pro)

## THM_PART_SLICE1D_XY

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      thm_part_slice1d_xy

    Purpose:
      Return the set of points at which a linear cut will be interpolated
      and corresponding plot labels.

    Calling Sequence:
      thm_part_slice1d_r, slice (xin=xin | yin=yin), xout=xout, yout=yout,
                          xaxis=xaxis, xtitle=xtitle

    Input:
      slice: 2D slice structure
      xin: x value at which to create cut perpendicular to the x axis
      yin: y value at which to create cut perpendicular to the y axis

    Output:
      xout: x coordinates of points to interpolate to
      yout: y coordinates of points tointerpolate to
      xaxis: final plot's x axis
      xtitle: title for final plot's x axis
      error: flag, 1 if error 0 if not

    Notes:

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice1d_xy.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice1d_xy.pro)

## THM_PART_SLICE2D_2DI

[Previous Routine] [Next Routine] [List of Routines]

     Name: thm_part_slice2d_2di.pro

     Purpose:  Helper function for thm_part_slice2d.pro
               Produces slice using 2D linear interpolation

     Note: This code is meant to preserve the functionality of
           thm_esa_slice2d for the new set of slices routines.

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_2di.pro)

## THM_PART_SLICE2D_3DI

[Previous Routine] [Next Routine] [List of Routines]

     Name: thm_part_slice2d_2di.pro

     Purpose:  Helper function for thm_part_slice2d.pro
               Produces slice by interpolating the volume
               in three dimensions then extracting a slice.

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_3di.pro)

## THM_PART_SLICE2D_CLIMIT

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      thm_part_slice2d_climit

    Purpose:
      Helper function for thm_part_slice2d_getxyz

    Input:
      dist: 3D particle data structure (UNSANITIZED)
      datatpoints: final averaged data array from thm_part_slice2d_getxyz
      units: string specifying units (e.g. 'eflux', 'df')
      subtract_counts: (float) subtract this many counts from all values
      count_threshold: (float) removed datapoints with less than this number of counts

    Output:
      none, modifies datapoints

    Notes:

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_climit.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_climit.pro)

## THM_PART_SLICE2D_COLLATE

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
     thm_part_slice2d_collate

    Purpose:
     Collate data aggregated as thm_part_slice2d_getdata loops over
     modes and times.  Data aggregation continues until a a change
     in energy or angle bins occurs (mode chance or other) or
     aggregation completes.  At those points this procedure is called
     to average the data, apply any necessary processing, concatenate
     data to output variables, and undefine the appropriate variables
     for the next loop.

    Input:
      data_t: summed data for all bins
      weight_t: summed weights for all bins

      rad_in: radial coords
      phi_in: phi coords
      theta_in: theta coords

      dr_in: radial bin widths
      dp_in: phi bin widths
      dt_in: theta bin widths

    Output:
      data_out: averaged data

      rad_out: radian coords
      phi_out: phi coords
      theta_out: theta corods

      dr_out: radian bin widths
      dp_out: phi bin widths
      dt_out: theta bin widths

      fail:  string output message, set if error occurs

    Notes:

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_collate.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_collate.pro)

## THM_PART_SLICE2D_COTRANS

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      thm_part_slice2d_cotrans

    Purpose:
      Helper function for thm_part_slice2d.
      Performs coordinate transformations from DSL to requested
      coordinates (COORD keyword to thm_part_slice2d).

    Input:
      probe: (string) spacecraft designation (e.g. 'a')
      coord: (string) target coordinates (e.g. 'gsm')
      trange: (double) two element time range for slice
      vectors: (float) N x 3 array of velocity vectors
      bfield: (float) magnetic field 3-vector
      vbulk: (float) bulk velocity 3-vector
      sunvec: (float) spacecraft-sun direction 3-vector

    Output:
      If 2d or 3d interpolation are being used then this will transform
      the velocity vectors and support vectors into the target coordinate system.
      The transformation matrix will be passed out via the MATRIX keyword.

    Notes:
      This assumes the transformation does not change substantially over the
      time range of the slice.

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_cotrans.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_cotrans.pro)

## THM_PART_SLICE2D_EBOUNDS

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      thm_part_slice2d_ebounds

    Purpose:
      Returns an array of gapless energy boundaries.  The number of
      elements returned will always be N+1 for N energy levels.

    Input:
      dist: 3D particle data structure

    Output:
      return value: Array of energy bin boundaries (# energy bins + 1)

    Notes:
      Energy levels are ordered differently between ESA/SST

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_ebounds.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_ebounds.pro)

## THM_PART_SLICE2D_FAC

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      thm_part_slice2d_fac

    Purpose:
      Helper function for thm_part_slice2d.
      Retrieves transformation matrix into field alligned
      coordinate systems.

    Input:
      probe: (string) spacecraft designation (e.g. 'a')
      coord: (string) target coordinates (e.g. 'phigeo')
      trange: (double) two element time range for slice
      mag_data: (string) name of tplot variable containing magnetic field data
      vectors: (float) N x 3 array of velocity vectors
      bfield: (float) magnetic field 3-vector
      vbulk: (float) bulk velocity 3-vector
      sunvec: (float) spacecraft-sun direction 3-vector

    Output:
      If 2d or 3d interpolation are being used then this will transform
      the velocity vectors and support vectors into the target coordinate system.
      The transformation matrix will be passed out via the MATRIX keyword.

    Notes:
      This assumes the transformation does not change substantially over the
      time range of the slice.

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_fac.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_fac.pro)

## THM_PART_SLICE2D_GEO

[Previous Routine] [Next Routine] [List of Routines]

     Name: thm_part_slice2d_geo.pro

     Purpose:  Helper function for thm_part_slice2d.pro
               Produces slice using each bin's boundaries.

     Input:
       data: N element array of data values
       rad: N element array of radial values
       phi: N element array of phi values
       theta: N element array of theta values
       dp: N element array of phi ranges
       dt: N element array of theta ranges
       dr: N element array of velocity ranges
       resolution: Single value (R) giving the number of points in each
                   dimension of the slice
       average_angle: Two element array specifying an angle range over which
                      averaging will be applied. The angle is measured
                      from the slice plane and about the slice's x-axis.
                        e.g. [-25,25] will average data within 25 degrees
                             of the slice plane about it's x-axis
       ct: Rotation matrix from DSL -> desired coordinates
       rot: Rotation matrix from given coordinates to specific rotation
            (e.g. DSL, GSM -> BV, perp_xy)
       mt: Rotation matrix from specified coords/rotation into
           the slice plane's coordinates

     Output:
       xgrid: R element array of x-axis values for the slice
       ygrid: R element array of y-axis values for the slice
       part_slice: RxR element array containing the slice data

     Other Keywords:
       msg_obj: Object reference to GUI message bar. If included useful
                console messages will also be output to GUI.
       msg_prefix: String prefix to be printed with progress messages.

     Caveats: This routine will slow as the number of bins (N) increases.
              Averaging will significantly lengthen the require time.

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_geo.pro)

## THM_PART_SLICE2D_GETDATA

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      thm_part_slice2d_getdata

    Purpose:
      Helper function for thm_part_slice2d.pro
      Returns an array of averaged data along with the corresponding
      bin centers and widths in spherical coordinates. This routine
      will apply energy range constraints and count thresholds.

    Input:
      dist_array: Array of 3d data structures
      units: String denoting data output units
      regrid: 3 Element array specifying the new number of points desired in
              phi, theta, and energy respectively.
      erange: Two element array specifying min/max energies to be used

    Output:
      data: N element array containing averaged particle data
      rad: N element array of bin centers along r (eV or km/s)
      phi: N element array of bin centers along phi
      theta: N element array of bin centers along theta
      dr: N element array of bin widths along r (eV or km/s)
      dp: N element array of bin widths along phi
      dt: N element array of bin widths along theta

    Notes:
      2014-11-07 count threshold moved to main routine
      2013-02-05 allow specific values for count threshold
      2012-12-21 - 2013-07-02 count threshold applied before averaging

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_getdata.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_getdata.pro)

## THM_PART_SLICE2D_GETMAG

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      thm_part_slice2d_getmag

    Purpose:
      Helper function for thm_part_slice2d.
      Retrieves an average of the b-field vectors over the
      slice's time range either from the particle structures
      or a user specified tplot variable.

    Input:
      ds: (pointer) Pointer array to particle distribution structures.
      trange: (double) Two element time range.
      mag_data: (string) Name of tplot variable containing b-field data.

    Output:
      return value: (float) Average magnetic field vector or -1 on error.

    Notes:

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_getmag.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_getmag.pro)

## THM_PART_SLICE2D_GETSPHERE

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      thm_part_slice2d_getsphere

    Purpose:
      Helper function for thm_part_slice2d_getdata
      Calculates the center and width of all bins in spherical coordinates.

    Input:
      dist: 3D data structure
      energy: flag to return energy as radial componenet instead of velocity

    Output:
      data: N element array containing interpolated particle data
      rad: N element array of bin centers along r (eV or km/s)
      phi: N element array of bin centers along phi
      theta: N element array of bin centers along theta
      dr: N element array of bin widths along r (eV or km/s)
      dp: N element array of bin widths along phi
      dt: N element array of bin widths along theta

    Notes:

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_getsphere.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_getsphere.pro)

## THM_PART_SLICE2D_GETSUN

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      thm_part_slice2d_getsun

    Purpose:
      Helper function for thm_part_slice2d.
      Retrieves sun vectors for all distributions within
      the specified time range and averages them.

    Input:
      ds: (pointer) Pointer array to particle distribution structures.
      trange: (double) Two element time range for the slice.

    Output:
      Returns averaged sun vector (3-vector float) on success or 0 on failure.

    Notes:
      This assumes that the spacecraft-sun vector is roughly constant over
      the time range of the slice.

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_getsun.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_getsun.pro)

## THM_PART_SLICE2D_GETVEL

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      thm_part_slice2d_getvel

    Purpose:
      Helper function for thm_part_slice2d.
      Retrieves an average of the bulk velocity vectors over the
      slice's time range either from the particle structures
      or a user specified tplot variable.

    Input:
      ds: (pointer) Pointer array to particle distribution structures.
      trange: (double) Two element time range.
      vel_data: (string) Name of tplot variable containing bulk velocity data (in km/s).

    Output:
      return value: (float) Average bulk velocity vector (m/s) or -1 on error.

    Notes:
      thm_esa_slice2d divides total flux over the time range by
      the total density; here the flux/density was previously
      calculated for each distribution and is now averaged.

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_getvel.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_getvel.pro)

## THM_PART_SLICE2D_INTRANGE

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      thm_part_slice2d_intrange

    Purpose:
      Helper function for thm_part_slice2d.
      Retrieves the indices of all samples in the specified
      time range from a particle distribution pointer.

    Input:
      ds: (pointer) Single particle distribution pointer.
      trange: (double) Two element array specifying the slice's time range.

    Output:
      return value: indices of all sample within trange.
      n: number of samples

    Notes:
      Uses the center of each sample's time window.

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_intrange.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_intrange.pro)

## THM_PART_SLICE2D_NCOUNT

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      thm_part_slice2d_ncount

    Purpose:
      Helper function for thm_part_slice2d_getxyz
      Converts one count value to requested units and returns converted data array.

    Input:
      dat: 3d data structure to be used
      units: string describing new units

    Output:
      return value: array of data corresponding to the specified number of counts

    Notes:

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_ncount.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_ncount.pro)

## THM_PART_SLICE2D_NN

[Previous Routine] [Next Routine] [List of Routines]

     Name: thm_part_slice2d_2di.pro

     Purpose:  Helper function for thm_part_slice2d.pro
               Produces slice using nearest neighbor interpolation.

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_nn.pro)

## THM_PART_SLICE2D_OLD

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
       thm_part_slice2d_old

    Purpose:

       **** Deprecated - Use THM_PART_SLICE2D ****

       Returns a 2-D slice of THEMIS ESA/SST particle distributions.
       This procedure works in conjunction with thm_part_dist_array.pro and
       thm_part_slice2d_plot_old.pro.

       There are three methods for generating slices:

       Geomtric:
         Each point on the plot is given the value of the bin it instersects.
         This allows bin boundaries to be drawn at high resolutions.

       2D Interpolation:
         Datapoints within the specified theta or z-axis range are projected onto
         the slice plane and linearly interpolated onto a regular 2D grid.

       3D Interpolation:
         The entire 3-dimensional distribution is linearly interpolated onto a
         regular 3d grid and a slice is extracted from the volume.

           Notes: - Interpolation may occur across data gaps or areas with recorded zeroes
                  - Higher resolution regridding will severely slow this method

    Calling Sequence:
        thm_part_slice2d, datArr, [datArr2, [datArr3, [datArr4]]], $
                          timewin = timewin, slice_time=slice_time, $
                          part_slice=part_slice

    Arguments:
     DATARR[#]: An array of pointers to 3D data structures.
                See thm_part_dist_array.pro for more.

    Keywords:

     SLICE_TIME: Beginning of time window in seconds since Jan. 1, 1970.  If
                 CENTER_TIME keyword set, then TIME is the center of the time widow
                 specified by the TIMEWIN keyword.
     TIMEWIN: Length in seconds over which to compute the slice.
     CENTER_TIME: Flag that, when set, centers the time window around the time
                  specified by SLICE_TIME keyword.
     UNITS: A string specifying the units to be used.
            ('counts', 'DF' (default), 'rate', 'crate', 'flux', 'eflux')
     ENERGY: Flag to plot data against energy (in eV) instead of velocity.
     LOG: Flag to apply logarithmic scaling to the radial mesure (i.e. energy/velocity).
          (on by default if /ENERGY is set)

     TWO_D_INTERP: Flag to use 2D interpolation method (described above)
     THREE_D_INTERP: Flag to use 3D interpolation method (described above)

     COORD: A string designating the coordinate system in which the slice will be
            oriented.  Options are 'DSL', 'GSM', 'GSE' and the following magnetic
            field aligned coordinates (field parallel to z axis).

          'xgse':  The x axis is the projection of the GSE x-axis
          'ygsm':  The y axis is the projection of the GSM y-axis
          'zdsl':  The y axis is the projection of the DSL z-axis
          'RGeo':  The x is the projection of radial spacecraft position vector (GEI)
          'mRGeo':  The x axis is the projection of the negative radial spacecraft position vector (GEI)
          'phiGeo':  The y axis is the projection of the azimuthal spacecraft position vector (GEI), positive eastward
          'mphiGeo':  The y axis is the projection of the azimuthal spacecraft position vector (GEI), positive westward
          'phiSM':  The y axis is the projection of the azimuthal spacecraft position vector in Solar Magnetic coords
          'mphiSM':  The y axis is the projection of the negative azimuthal spacecraft position vector in Solar Magnetic coords

     ROTATION: The rotation keyword specifies the orientation of the slice plane
               within the given coordinates (BV and BE will be invariant between
               coordinate systems).

         'BV':  The x axis is parallel to B field; the bulk velocity defines the x-y plane
         'BE':  The x axis is parallel to B field; the B x V(bulk) vector defines the x-y plane
         'xy':  (default) The x axis is along the coordinate's x axis and y is along the coordinate's y axis
         'xz':  The x axis is along the coordinate's x axis and y is along the coordinate's z axis
         'yz':  The x axis is along the coordinate's y axis and y is along the coordinate's z axis
         'xvel':  The x axis is along the coordinate's x axis; the x-y plane is defined by the bulk velocity
         'perp':  The x axis is the bulk velocity projected onto the plane normal to the B field; y is B x V(bulk)
         'perp_xy':  The coordinate's x & y axes are projected onto the plane normal to the B field
         'perp_xz':  The coordinate's x & z axes are projected onto the plane normal to the B field
         'perp_yz':  The coordinate's y & z axes are projected onto the plane normal to the B field

     SLICE_X/SLICE_NORM: These keywords respectively specify the slice plane's
                   x-axis and normal within the coordinates specified by
                   COORD and ROTATION. Both keywords take 3-vectors as input.

                   If SLICE_X is not specified then the given coordinate's
                   x-axis will be used. If SLICE_X is not perpendicular to
                   the normal it's projection onto the slice plane will be used.
                   An error will be thrown if no projection exists.

                   If SLICE_NORM is not specified then the given coordinate's
                   z-axis will be used (slice along by x-y plane in those
                   coordinates).

           examples:
             Slice plane perpendicular to DSL z-axis using [3,2,0] as plane's x-axis:
             (this is the same as only using SLICE_X=[3,2,1])
               COORD='dsl' (default), ROTATION='xyz' (default), SLICE_X=[3,2,1]

             Slice plane perp. to GSE x-axis, bulk velocity used to define plane's x-axis:
               COORD='gse', ROTATION='xvel', SLICE_NORM=[1,0,0], SLICE_X=[0,1,0]

             Slice plane along the B field and radial position vectors, B field used as slice's x-axis:
               COORD='rgeo', SLICE_NORM=[0,1,0], SLICE_X=[0,0,1]

     DISPLACEMENT: Value in m/s that specifies how far from the origin the slice
                   plane will be cut.

           example:
             Slice plane cut at Z_gse = 500
               COORD='gse', ROTATION='xyz' (default), DISPLACEMENT=500.

     AVERAGE_ANGLE: Two element array specifying an angle range over which
                    averaging will be applied. The angle is measured
                    from the slice plane and about the slice's x-axis;
                    positive in the right handed direction. This will
                    average over all data within that range.
                        e.g. [-25,25] will average data within 25 degrees
                             of the slice plane about it's x-axis

     VEL_DATA: Name of tplot variable containing the bulk velocity data.
               This will be used for slice plane alignment and subtraction.
               If not set the bulk velocity will be automatically calculated
               from the distribution (when needed).
     MAG_DATA: Name of tplot variable containing magnetic field data.
               This will be used for slice plane alignment.
     ERANGE: Two element array specifying the energy range to be used.
     COUNT_THRESHOLD: Mask bins that fall below this number of counts after averaging.
                    (e.g. COUNT_THRESHOLD=1 masks bins with counts below 1)
     RESOLUTION: Integer specifying the resolution along each dimension of the
                 slice (defaults:  2D/3D interpolation: 150, geometric: 500)
     SMOOTH: An odd integer >=3 specifying the width of the smoothing window in #
             of points. Even entries will be incremented, 0 and 1 are ignored.
             Smoothing is performed with a gaussian convolution.

     REGRID: (2D/3D Interpolation only)
             A three element array specifying regrid dimensions in phi, theta, and
             energy respectively. If set, all distributions' data will first be
             spherically interpolated to the requested reslotution using the
             nearest neighbor.  The resolution in energy will only be interpolated
             to integer multiples of the original resolution (e.g. data with 16
             energies will be interpolated to 32, 48, ...)

     THETARANGE: (2D interpolation only)
                 Angle range, in degrees [-90,90], used to calculate slice.
                 Default = [-20,20]; will override ZDIRRANGE.
     ZDIRRANGE: (2D interpolation only)
                Z-Axis range, in km/s, used to calculate slice.
                Ignored if called with THETARANGE.

     MSG_OBJ: Object reference to GUI message bar. If included useful
              console messages will also be output to GUI.

    Output:
     PART_SLICE: Structure to be passed to thm_part_slice2d_plot.
          {
           data: two dimensional array (NxN) containing the data to be plotted
           xgrid: N dimensional array of x-axis values for plotting
           ygrid: N dimensional array of y-axis values for plotting
           probe: string containing the probe
           dist: string or string array containing the type(s) of distribution used
           mass: assumed particle mass from original distributions
           coord: string describing the coordinate system used for the slice
           rot: string describing the user specified rotation (N/A for 2D interp)
           units: string describing the units
           twin: time window of the slice
           rlog: flag denoting radial log scaling
           ndists: number time samples included in slice
           type: flag denoting slice type (0=geo, 2=2D interp, 3=3D interp)
           zrange: two-element array containing the range of the un-interpolated data
           rrange: two-element array containing the radial range of the data
           trange: two-element array containing the numerical time range
           shift: 3-vector containing any translations made in addition to
                  requested rotations (e.g. subtracted bulk velocity)
           bulk: 3-vector containing the bulk velocity in the slice plane's coordinates
           sunvec: 3-vector containing the sun direction in the slice plane's coordinates
           coord_m: Rotation matrix from original data's coordinates (DSL) to
                    those specified by the COORD keyword.
           rot_m: Rotation matrix from the the specified coordinates to those
                defined by ROTATION.
           orient_m: Rotation matrix from the coordinates defined by ROTATION to
                     the coordinates defined by SLICE_NORM and SLICE_X
                     (column matrix of new coord's basis).
           }

    CAVEATS: Due to IDL software constraints regions containing no data
             are assigned zeros instead of NaNs.

    NOTES:
      In general this code makes the following assumptions about the particle data:
        - Look directions, energies, and assumed particle mass may vary between
          modes but not within a mode (this is checked within the code).
        - If assumed mass varies greatly between modes then the mass field in
          the output structure should be ignored.  This will prevent 1D slice
          plots from being made with the output

    CREATED BY: A. Flores
                Based on work by Bryan Kerr and Arjun Raj

    EXAMPLES:  see the crib file: thm_crib_part_slice2d.pro

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_old.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_old.pro)

## THM_PART_SLICE2D_ORIENTSLICE

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      thm_part_slice2d_orientslice

    Purpose:
      Helper function for thm_part_slice2d.
      Performs transformation into user specified coordinates.
      This transformation is applied after the COORD and ROTATION
      transformation have been performed.

    Input:
      slice_z: (float) 3 vector specifying the slice's normal
      slice_x: (float) 3 vector to be projected into the slice plane
      vectors: (float) N x 3 array of velocity vectors
      bfield: (float) magnetic field 3-vector
      vbulk: (float) bulk velocity 3-vector
      sunvec: (float) spacecraft-sun direction 3-vector

    Output:
      If 2d or 3d interpolation are being used then this will transform
      the velocity vectors and support vectors into the target coordinate system.
      The transformation matrix will be passed out via the MATRIX keyword.

    Notes:

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_orientslice.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_orientslice.pro)

## THM_PART_SLICE2D_REGRIDSPHERE

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      thm_part_slice2d_regridsphere

    Purpose:
      Helper function for thm_part_slice2d_getdata
      Spherically interpolates a structure's data to a specified regular grid
      and returns the center and width of all bins in spherical coordinates.

    Input:
      dist: 3D data structure
      energy: flag to return radial componenets in eV instead of km/s
      regrid: 3 Element array specifying the new number of points in
              phi, theta, and energy respectively.

    Output:
      data: N element array containing interpolated particle data
      bins: N element array of flags denoting datapoint validity
      rad: N element array of bin centers along r (eV or km/s)
      phi: N element array of bin centers along phi
      theta: N element array of bin centers along theta
      dr: N element array of bin widths along r (eV or km/s)
      dp: N element array of bin widths along phi
      dt: N element array of bin widths along theta

    Notes:

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_regridsphere.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_regridsphere.pro)

## THM_PART_SLICE2D_RLOG

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      thm_part_slice2d_rlog

    Purpose:
      Apply radial log scaling to aggregated velocity/energy vectors.

    Input:
      r: N element array of radii
      dr: N element array of radial bin withds (full width)
      displacement: scalar denoting slice's offset of the origin along the normal

    Output:
      None, modifies input variables by tranforming into log space and normalizing
      along the range of the data.

    Notes:

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_rlog.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_rlog.pro)

## THM_PART_SLICE2D_ROTATE

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      thm_part_slice2d_rotate

    Purpose:
      Helper function for thm_part_slice2d.
      Performs transformation from coordinates specified by
      COORD (thm_part_slice2d) to those specified by
      ROTATION (thm_part_slice2d).

    Input:
      probe: (string) spacecraft designation (e.g. 'a')
      coord: (string) target coordinates (e.g. 'phigeo')
      trange: (double) two element time range for slice
      vectors: (float) N x 3 array of velocity vectors
      bfield: (float) magnetic field 3-vector
      vbulk: (float) bulk velocity 3-vector
      sunvec: (float) spacecraft-sun direction 3-vector

    Output:
      If 2d or 3d interpolation are being used then this will transform
      the velocity vectors and support vectors into the target coordinate system.
      The transformation matrix will be passed out via the MATRIX keyword.

    Notes:
      This assumes the transformation does not change substantially over the
      time range of the slice.

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_rotate.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_rotate.pro)

## THM_PART_SLICE2D_S2C

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      thm_part_slice2d_s2c

    Purpose:
      Helper function for thm_part_slice2d_getxyz
      Converts spherical coordinates to cartesian

    Input:
      r: N element array of radial values (can be any dimensions)
      theta: N element array of theta values ( " )
      phi: N element array of phi values ( " )

    Output:
      vec: Nx3 array of cartesian values in x,y,z order

    Notes:
      could probably just use sphere_to_cart?

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_s2c.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_s2c.pro)

## THM_PART_SLICE2D_SMOOTH

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      thm_part_slice2d_smooth

    Purpose:
      Helper function for thm_part_slice2d.
      Smooths the output data by applying a gaussian blur.

    Input:
      part_slice: (float) N x N array containing the slice data
      width: (int) width of smoothing window in points in both x and y

    Output:
      None, modifies part_slice.

    Notes:

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_smooth.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_smooth.pro)

## THM_PART_SLICE2D_SUBTRACT

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      thm_part_slice2d_subtract

    Purpose:
      Helper function for thm_part_slice2d.
      Subtracts bulk velocity vector from velocity array.

    Input:
      vectors: (float) N x 3 array of particle vectors
      vbulk: (float) bulk velocity 3-vector
      vel_data: (string) name of tplot variable containing bulk velocity data

    Output:
      none, modifies vectors

    Notes:
      This shift should NOT be applied when using the geometric method.

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
    $LastChangedRevision: 20331 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_subtract.pro $

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_subtract.pro)

## THM_PART_SLICE_EXTRACT

[Previous Routine] [Next Routine] [List of Routines]

    Procedure: thm_part_slice_extract

    Purpose: Returns a 2-D slice of a scattered 3-D distribution along
             the designated plane.  Points near the slice plane are
             projected onto the plane and then interpolated onto a regular
             grid using the nearest neighbor method.

    Arguments:
     DATA: An array of N datapoints to be used.
     VECTORS: An array of N x 3 datapoints designating, respectively,
              the x,y,z values for each point in DATA
     RESOLUTION: The number of points along each dimention of the
                 interpolated slice

    Input Keywords:
     CENTER: A vector designating the slice plane's center, default = [0,0,0]
     NORMAL: A vector designating the slice plane's normal, default = [0,0,1]
     XVEC: A vector whose projection into the slice plane will form its
           x-axis. The data's x-axis is used by default, if no projection
           exists an error will be returned
     SLICE_WIDTH: The width of the slice given in % (of data range)

    Output Keywords:
     XGRID: Array of x-locations for the slice.
     YGRID: Array of y-locations for the slice.
     FAIL: This keyword will contain a message in the event of an error

(See projects/themis/spacecraft/particles/slices/core/thm_part_slice_extract.pro)

## THM_UI_SLICE2D_BAR__DEFINE.PRO

[Previous Routine] [List of Routines]

    NAME:
     thm_ui_slice2d_bar__define.pro

    PURPOSE:
     Object created for the 2d slices interface. Allows scrolling back
     and forth over a temporal series of slices.

    CALLING SEQUENCE:
     sb = obj_new('THM_UI_SLICE2D_BAR', parentID, xScreenSize, (windowStorage, loadedData, drawObject,) $
                                       statusbar=statusbar, value = 500, range = [0,1000])

    ATTRIBUTES:
     id: slider widget's ID
     parent: parent widget's ID
     xsize: screen size, in pixels, of the slider bar
     range: the numerical integer range about which the slider can move (in sec), [0,1000] by default
     value: the current value of the slider, zero (fully left) in the absence of data
     ok:  flag indicating whether the slider should be sensitized

    PUBLIC METHODS:
     getValue: Allows retrieval of value, range, and xsize
     setValue: Allows setting of value and xsize, mainly for the purpose of gui resize events
     update: Update procedure to be called when:
                 -new plots have been generated (after setValue)
                 -there was an error (after setValue)
                 -events are processed (w/ EVENT keyword)

    NOTES:

    HISTORY:
     Initial version: 4-02-10
     Added title 3-5-12

(See projects/themis/spacecraft/particles/slices/core/thm_ui_slice2d_bar__define.pro)