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

Last modified: Wed Jul 30 18:17:37 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)