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

Last modified: Fri Nov 7 18:17:52 2025.

# Directory Listing of Routines

# general/missions/fast/fa_general/fast_orbit

- AURORAL_ZONE
- AURORAL_ZONE_SSC
- DATESEC_DOY
- DATETIMESEC_DOY
- DIPOLE_OFFSET
- LABEL_FOOT_TICKS
- MAG_TO_GEO
- PLOT_FA_CROSSING
- RERANGE
- SECOFDAY
- TERMINATOR
- TRANSFORM_MAG_GEO

# Routine Descriptions

## AURORAL_ZONE

[Next Routine] [List of Routines]

     FUNCTION:	auroral_zone

     PURPOSE:	IDL function to calculate auroral zone position as a
    		function of magnetic local time (mlt: 0.0-24.0 hours),
    		activity index Q (q: 0-6).
    		Returns corrected geomagnetic colatitude in radians.

     OPTIONS:	To return poleward edge, set poleward.
    		To return latitude, set latitude.
    		To return value for southern oval, set south.
    		To return value in degrees, set degrees.

     See Holzworth & Meng, GRL 2, p. 377, 1975.

     Originally written by J. Clemmons, June 1993.
     Corrected by J.Rauchleiba under the direction of Mike Temerin Apr 1997.

(See general/missions/fast/fa_general/fast_orbit/auroral_zone.pro)

## AURORAL_ZONE_SSC

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

     FUNCTION:   auroral_zone_ssc

     PURPOSE:    Given an array of MLT values, returns latitudes of the
                 auroral zone boundaries.  The definition of the
                 auroral zone is that used by the Satellite Situation
                 Center.  It is basically the area between two
                 sinusoidally-perturbed concentric circles centered on
                 the magnetic pole.
                 Output is equatorward latitude in Geomagnetic
                 Coordinates, and in radians unles DEGREES is set.
     ARGUMENTS:

       MLTINPUT  The input array of MLT values.  Elements should look
                 like [0, .1, .2, ...,  23.9, 24.0]

     KEYWORDS:

       POLEWARD  Set this to a named variable to receive the poleward
                 latitude values.
       SOUTH     Set this keyword to one if a reflection through the
                 magnetic equator is desired.  This gives
                 S. Hem. coordinates.
       DEGREES   Set this keyword to get the coordinates in degrees,
                 otherwise output is in radians.

     NOTES:      The definition of the auroral zones used here is that
                 accepted by the SSC.  See also: auroral_zone.pro.

     CREATED:    By Joseph Rauchleiba
                 98/1/6

(See general/missions/fast/fa_general/fast_orbit/auroral_zone_ssc.pro)

## DATESEC_DOY

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

     FUNCTION:
     	 DATESEC_DOY

     DESCRIPTION:

     	take args for year and day of year and return
    	(double float) seconds since 1 Jan 1970, 00:00 UT.

     USAGE:

        	print, datesec_doy(75, 134)

    	gives result:
    	 1.6925760e+08

     NOTES:
    	does not handle years past 1999; year must be two digit.

     REVISION HISTORY:

    	@(#)datesec_doy.pro	1.3 01/26/99
     	written by Ken Bromund, Space Sciences Lab, Berkeley.  May, 1991

(See general/missions/fast/fa_general/fast_orbit/datesec_doy.pro)

## DATETIMESEC_DOY

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

     FUNCTION:
     	 DATETIMESEC_DOY

     DESCRIPTION:

    	function to return seconds since 1/1/1970 00:00 UT, from date and
     	time given as day, month, year, hour, minute, second, millisecond.

     USAGE (SAMPLE CODE FRAGMENT):

        ; set up a date and time (21 Mar '91, 00:01:01.000)

    	doy = 80
    	year = 91
    	hour = 0
    	min = 1
    	sec = 1
    	msc = 0

        ; convert to seconds

    	sec_date_time = datetimesec_doy(year, doy, hour, min, sec, msc)

        ; print it out

    	PRINT, sec_date_time

     --- Sample output would be

    	669517261

     NOTES:

    	If any of the fields are are out of range, the value will be carried.
    	e.g. given date and time of 31/12/90, 25:01:00.1001, this will be
    	converted to   1/1/91, 01:01:01: 001
    	If any of the input values are negitive, this is an error and -1 will

    	This function can return seconds of days, or seconds since 1970 only
    	by calling it with dates or times set to zero.

    	If input values are arrays, then an array of N_ELEMENTS(inputs vals)
    	of date strings and remainders will be returned.  The number of
    	array elements for all input parameters must be the same

     REVISION HISTORY:

    	@(#)datetimesec_doy.pro	1.2 01/26/99
     	Originally written by Jonathan M. Loran,  University of
     	California at Berkeley, Space Sciences Lab.   Sep. '91

    	Revised to handle arrays of input values, JML, Mar. '92

(See general/missions/fast/fa_general/fast_orbit/datetimesec_doy.pro)

## DIPOLE_OFFSET

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

     FUNCTION:	dipole_offset

     PURPOSE:	Calculate the location of the dipole using the IGRF
    		coefficients and their secular variation.  IGRF coefficients
    		are the coefficients used in the spherical harmonic
    		expansion of the earth's magnetic field and there is a
    		standard formula for converting the first few of these
    		coefficients to dipole offset.

    		This version is accurate for years 1995-2000

    		Returns a 3-element vector in kilometers.

     INPUT:	Optional argument is 4-digit year

     Algorithm by:	Mike Temerin
     Written by:	J.Rauchleiba  4/8/97

(See general/missions/fast/fa_general/fast_orbit/dipole_offset.pro)

## LABEL_FOOT_TICKS

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

     PROCEDURE:

        label_foot_ticks

     PURPOSE:

        Keeps track of parasites on the pedal area of the body.  Adds
        timeticks and text labels to a path plotted on a map of the
        earth.  The latitudes and longitudes, as well as the
        corresponding time array, must be passed through keywords.  This
        procedure was written for plot_fa_crossing.pro.

     KEYWORDS:

        TIME_ARRAY The time array corresponding to the FLAT and FLNG
                   arrays.
        LATITUDE   The latitude array.
        LONGITUDE  The longitude array.
        LATLIM     The absolute value of lattitude above which (below in
                   S. hem.) to confine timeticks on the plot. Default is
                   45 degrees.
        INTERVAL   The interval in seconds on which ticks are marked.
                   Default is 300 sec.
        COLOR      The color of the labels

     CREATED:

        BY         J.Rauchleiba
        DATE       97-9-12

(See general/missions/fast/fa_general/fast_orbit/label_foot_ticks.pro)

## MAG_TO_GEO

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

    PROCEDURE:	mag_to_geo

    PURPOSE:	Converts lattitude and longitude between MAG
    		and GEO coordinates.
    		Uses a simple transformation matrix from Kivelson
    		and Russell, "Intro to Space Physics" which is not
    		very accurate in the polar regions.

    PARAMETERS:	lat	The array of lattitudes.(In radians unless
    			degrees keyword set.)
    		lon	The array of longitudes.(in radians unless
    			degrees keyword set.)

    KEYWORDS:	degrees	Set this if both input and output are to be
    			in degrees.
    		mag	Set this to do the inverse transformation,
    			GEO to MAG coordinates.
    Created by:	J.Rauchleiba	1/7/97

(See general/missions/fast/fa_general/fast_orbit/mag_to_geo.pro)

## PLOT_FA_CROSSING

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

    PROCEDURE:	plot_fa_crossing

    PURPOSE:

    	Plots magnetic footprint of spacecraft across earth. (FLAT,FLNG)
    	Shows the night/day terminator, auroral ovals, apogee and perigee
    	footprints, etc.  (See examples below.)

           Keywords are grouped into categories: TIMESPAN, VIEW, DISPLAY,
           AURORAL ZONE, MISCELLANEOUS.

     TIMESPAN KEYWORDS:

    	ORBIT	The orbit to plot. If unset, will plot over interval
    		containing present time and show craft position right now
    		(unless TMIN and TMAX are set).  ORBIT cannot be greater than
    		the last orbit listed in the predicted orbit almanac file.
      TMIN, TMAX	Time points to be included on the chart.  Use these if
                   you want to display timespan in distant future.
                   Should not be more than a couple hours apart.  Format
                   of TMIN and TMAX must be the type of string accepted
                   by time_double() or a double float in seconds since
                   1970.  ORBIT must not be set if these keywords are to
                   be used.  These times will be labeled on the map as t1
                   and t2.  (Good for showing AOS and LOS taken from
                   contact schedules.)
    	XMARK	Set this to a time (string or double float) to have that point
                   labeled on the map as a big X.  If none of ORBIT,
                   TMIN, TMAX are set then this time will be used as the
                   reference time for which to create the plot.  (Good
                   for showing conjunctions.)

     VIEW KEYWORDS:

       KIRUNA, POKER, WALLOPS, MCMURDO, CANBERRA, SANTIAGO, BERKELEY:
    		Set any of these for an overhead view of the station.
       VIEWPOINT   This allows arbitrary views of the Earth. Should be a
                   3-element array designating lattitude, longitude, and
                   rotation in degrees.
    	WHOLE	If set, will not confine plot to polar regions.
    	SOUTH	Set to view earth from directly over South Pole.
         MAGPOLE   View from above the magnetic pole with magnetic local
                   noon at the top of the plot.  Gridlines are still
                   geographic.  Poles are not symmetric because of the
                   eccentric dipole.  (When this keyword is not set
                   the display defaults to above the geographic poles,
                   with geographic local noon at the top.)
            ZOOM   Enlarges the map. 1 is normal, 2 is twice as big.
                   See WINSIZE keyword for zooming in postscript mode.

     DISPLAY KEYWORDS:

         WINSIZE	The width of the plot window in pixels. Default width is
                   640.  Height is scaled automatically so that lattitude
                   lines will be circular when output on a Tek printer:
                   H = W * 1.031.  In PostScript mode (POST keyword set),
                   WINSIZE acts like a magnification factor; WINSIZE=10
                   is normal.
    	  PC	Set this to nonzero if you are using a windowing system
    		that does not provide backing store to retain hidden
    		windows.  This keyword also sets the VECTOR_FONTS keyword.
    	GREY	Set this keyword to output the plot in greyscale.
    		(Run @startup to restore colortable.)
           FILL    Fills oceans and continents with solid color to make a
                   pretty plot.  Setting this keyword when printing to
                   a color printer is discouraged.
      VECTOR_FONTS Disable switch to device (hardware) font from
                   (default) Hershey vector-drawn fonts.  Device fonts
                   may be prettier, but vector fonts are device
                   independent.
    	POST    Set this to a filename to direct the ouput to an 8-bit color
                   postscript file instead of the graphics window.  When
                   viewing the postscript file, be sure your viewer is
                   set to 8 bits, not 24, and that it is displaying
                   "perfect colors".  (Do not add ".ps" to the name.)
            GIF    Captures the image on the output graphics window to a
                   GIF file.  (Add ".gif" to the name yourself.)

     AURORAL ZONE KEYWORDS:

        ACTIVITY	Set the Activity Index of aurora. ( 0-6, default 3)
         SSCZONE   Show the auroral zone used by the Satellite Situation
                   Center instead of the one from Holzworth and Meng.
                   (THIS IS NOT PERFECTED YET.) See auroral_zone_ssc.pro
                   and notes below.

     MISCELLANEOUS KEYWORDS:

          POLAR    Plots the magnetic footprint of the POLAR spacecraft
                   and information about its closest approach to that of
                   FAST.  Good for finding conjunctions or displaying
                   known ones. (For a description of how POLAR orbit data
                   is obtained, see the documentation for
                   get_po_orbit.pro.)
       DRAG_PROP   If set, the orbit propagator will include the effects
                   of atmospheric drag.  The orbit track may be
                   inaccurate by a few degrees for propagations as short
                   as a few weeks.  This keyword minimizes this error.
    ALMANAC_INFO   Prints a line under the plot title telling the orbit
                   file used, the last epoch in that orbit file, and
                   whether or not drag was included in the orbit propagation.

       EXAMPLES:   Show what FAST is doing now, and make it pretty:

                   IDL>  plot_fa_crossing, /fill

                   Show what FAST is doing for Christmas, make output
                   greyscale, and copy output to a GIF file:

                   IDL>  plot_fa_crossing, xmark='98-12-25/00:00:00', $
                         gif='~/images/northpole.gif', /grey

                   Show the polar crossing of orbit 3000 from a
                   bird's-eye view over Canberra, and send the output to
                   an 8-bit color postscript file:

                   IDL>  plot_fa_crossing, /can, post='~/images/orb3000', $
                         orbit=3000

    NOTES ON THE
    AURORAL ZONE:	The auroral zone is drawn using a procedure by Jim
                   Clemens (suggested by Holzworth & Meng, and corrected
                   by Mike Temerin).  The source for this procedure is
                   "Mathematical Representation of the Auroral Oval",
                   R.H. Holzworth and C.-I. Meng, Geophysical Research
                   Letters, Vol.2, No.9, Sept 1975.

                   The mathematical representation of the auroral ovals
                   is found by fitting Feldstein statistical ovals in
                   corrected geomagnetic coordinates to a 7-parameter
                   Fourier series:

    		theta =  A1  +  A2 cos(phi + A3)
    		      +  A4 cos(2phi + 2A5)
    		      +  A6 cos(3phi + 3A7)

    		theta = corrected geomagnetic co-lattitude
    		phi = 2(pi)(MLT)/(24hrs)

                   The best fit constants are found for each value of
                   Q=0..6, where Q is the activity index which describes
                   how quiet (0) or active (6) the Feldstein auroral
                   ovals are.  The characteristic radius A1 of the ovals
                   increases monotonically with Q. (Source: Holzworth and
                   Meng.)

                   The function azonloc.pro generates the southern
                   auroral oval by reflection of the northern oval
                   through the magnetic equator.

                   The formula in Holzworth and Meng gives the ovals in
                   corrected geomagnetic coordinates.  The procedure
                   transform_mag_geo.pro converts them to geograhic
                   coordinates using the eccentric dipole model.

    CREATED BY:    J.Rauchleiba            96-12-20

(See general/missions/fast/fa_general/fast_orbit/plot_fa_crossing.pro)

## RERANGE

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

    PROCEDURE:	rerange

    PURPOSE:	Reformats arrays so they may be plotted as
    		lattitude and longitude.  Changes arrays so
    		that they are in the intervals [-pi/2, +pi/2]
    		and [-pi, +pi]. Can change both lattitude and
    		longitude or just longitude.

    ARGUMENTS:	lng	The longitude array in radians.
    		lat	The corresponding lattitude array in
    			radians. (Optional)
    KEYWORDS:	degrees	Set this to return the arrays in degrees.

    Created by:	J.Rauchleiba	12/20/96

(See general/missions/fast/fa_general/fast_orbit/rerange.pro)

## SECOFDAY

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

     FUNCTION:
     	 SECOFDAY

     DESCRIPTION:

     Function to return seconds of a day, given the time in hours, minutes,
     seconds and milliseconds.

     USAGE (SAMPLE CODE FRAGMENT):

        ; set up a time (00:01:01.001)

    	hour = 0.
    	min = 1.
    	sec = 1.
    	msc = 1.

        ; convert to seconds

    	seconds = secofday(hour, min, sec, msc)

        ; print it out

    	PRINT, seconds

     --- Sample output would be

    	61.001

     NOTES:

    	If input seconds is an array, then an array of N_ELEMENTS(inputs vals)
    	of date strings and remainders will be returned.

    	The number of array elements for all input parameters must be the same

     REVISION HISTORY:

    	@(#)secofday.pro	1.2 06/04/95
     	Originally written by Jonathan M. Loran,  University of
     	California at Berkeley, Space Sciences Lab.   Sep. '91

    	Revised to handle arrays of input values, JML, Jan. '92

(See general/missions/fast/fa_general/fast_orbit/secofday.pro)

## TERMINATOR

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

    PROCEDURE:	terminator

    PURPOSE:	Generates lattitude and longitude arrays for the
    		night/day terminator given an input time.
    		Values returned are in Geographic coordinates.

    KEYWORDS:

    	TIME	The input time in seconds since 1970.

    POSITIONAL
    PARAMETERS:

    	TLAT	The name of the array in which to return the
    		lattitude values of the terminator.
    	TLNG	The name of the array in which to return the
    		longitude values of the terminator

    Created by:	J.Rauchleiba	97-25

(See general/missions/fast/fa_general/fast_orbit/terminator.pro)

## TRANSFORM_MAG_GEO

[Previous Routine] [List of Routines]

     PROCEDURE:	transform_mag_geo

     PURPOSE:	Convert lattitudes and longitudes between MAG and GEO
    		coordinate systems using the eccentric dipole model.
    		Transformation is from MAG to GEO unless INVERSE is set.
    		Transformation is performed at <Re> + 100km = 6472.1 km

     INPUTS:

       LAT		The input lattitude array. (Not altered)
       LNG		The input longitude array. (Not altered)
       TLAT	Named variable to accept transformed lattitudes.
       TLNG	Named variable to accept transformed longitudes.

     KEYWORDS:

       YEAR	The 4-digit year.
       DEGREES	If nonzero, input and ouput in degrees.
       INVERSE	If nonzero, tranformation is from GEO to MAG.

     NOTES:

       MAG --> GEO:
       When transforming from MAG to GEO, LAT and LNG are assumed to
       refer to points Re=6372.1 km from the earth's dipole center.
       (This does not necessarily place them on the surface of the earth.)
       The points are propagated to <Re> + 100km and then their
       coordinates are converted to the GEO system through a rotation
       followed by a translation.

       This procedure is inaccurate for points where field lines are nearly
       orthogonal to lines through the dipole center, i.e. near the equator.

       GEO --> MAG:
       When transforming from GEO to MAG, LAT and LNG are assumed to
       refer to points Re + 100km from the center of the earth.
       Since this one is simply the inverse of the above transformation, we
       do the inverse translation followed by the inverse rotation.
       Right now, the GEO to MAG transformation is less accurate than its
       inverse; it does not propagate along field lines during the
       translation to the dipole center.

     WRITTEN BY:	J. Rauchleiba	4/14/97
     ALGORITHM BY: M. Temerin, G. Kaplan, J. Rauchleiba

(See general/missions/fast/fa_general/fast_orbit/transform_mag_geo.pro)