Document title: Source code documentation for DE SAI data on NDADS Project: DE NDADS Datatype: SAI Super-EID: DOCUMENT There may be other documents also identified by this super-EID. NDADS filename: DOCUMENT_SAI_SSCDOC.SFD TRF entry B46578.txt in NSSDC's controlled digital document library. Feb. 1998. Document text follows: ---------------------- TYPE_OF_FILE_NAMES: *.FOR files contain documented software source code, *.XMP files contain input and output for sample runs. OVERVIEW_OF_SOFTWARE: The software source code included in each archival volume has two main functions: 1) to align the image data in order to reconstruct the original image as seen by the instrument; and 2) to associate geophysical coordinates with the image as a whole and with individual pixels. Routines are also provided to open image files and set up common blocks required by display and coordinate software, and to convert pixel values to luminosities. Preflight calibration data are used. If the original image is to be displayed, the window on the output device and the portion of the image to be displayed in the window must be specified as described below. To draw geometric features such as the limb of the Earth and the terminator over the displayed image, identical window and image specifications must be provided. Geographic positions of selected locations on the image may be determined using other subroutines provided here. Subroutines needed for the user's output graphics device are described functionally, but must be supplied by the user. Coordinates may also be associated with image data without displaying the image. Subroutines are provided to calculate geographic or GEI coordinates for a given mirror position and pixel number. Software is also provided to carry out the inverse procedure. This approach is useful for remapping an image to a polar or some other convenient projection. GENERAL_DESCRIPTIONS: 1. Set up The subroutine CURRENT_IMAGE prompts the user to specify an image file and to set the dimensions of the display window that will contain it. CURRENT_IMAGE is provided to demonstrate the specification of arguments necessary for displaying an original image and mapping coordinates onto it. It can be modified to suit the user's needs. The subroutine IMAGEIN reads and unpacks the image data file, and sets up common blocks that are used by all software requiring access to pixel values. The set up required for later coordinate calculations is accomplished with a call to the subroutine SETCRD, which is described below. SETCRD invokes MOTION to calculate spacecraft positions and SETIMCOORD and SETWNCOORD to establish view coordinates for the image and display window. 2. Image alignment and display The display software produces successive output lines of pixels to be written vertically on the graphics screen from top to bottom. The resulting image conforms to the standards described in the SAIDOC.SFD, following the keyword IMAGE_DISPLAY_ALGORITHM. Start positions of successive output lines will progress from left to right or from right to left in correspondence with the instrument's scanning direction. The three scan-line adjustments will have been applied as needed to improve pixel alignment. The user should establish a rectangular portion of the display screen as the output window and specify top, bottom, left, and right window edges in integer screen coordinates. It is assumed that those coordinates will increase from top to bottom and from left to right. Each output line will be accompanied by its start position along the top edge of the window. The user must supply the DSPLIN graphics output subroutine to display the line of pixels proceeding down from its start position. The user must also provide SETPLT and WRAPUP graphics subroutines as described below. DISPLAY_IMAGE is the primary subroutine involved in displaying an original image. The top-level program IMDSP is provided to demonstrate how to get image and screen window specifications with a call to CURRENT_IMAGE and to then display that image by calling DISPLAY_IMAGE. Any portion of an image can be displayed to any magnification inside the window. Nothing is displayed outside of the window boundaries. The mirror location count given by CENTRMLC indicates which scan line is placed in the center of the window. PIXOFF is an offset along the vertical scan line that indicates which pixel in the scan line is located at the top of the window. If CENTRMLC is zero, the default center scan for that photometer is used. Two expansion schemes are provided with DISPLAY_IMAGE. The first method expands the image to the requested magnification by repeating the nearest pixel value with no interpolation. The second method employs linear interpolation based on the distance from adjoining pixels. The DISPLAY_IMAGE subroutine allows different interpolation schemes and magnification factors to be used in both the vertical and horizontal expansions. The top-level program IMDSP, however, requests only one magnification factor and one expansion scheme to be used in both directions. The parameter MAXLENGTH is used to limit the length of a display line to 768. Although pixel values range from zero to 255, science data is only in the range from zero to 127. Setting the CSMTCS2 flag to .TRUE. as is done by IMDSP signals that pixel values greater than 127 be set to zero. The pixel histogram values given in the DIN array contained in the file header record may be helpful for establishing the color table settings. 3. Coordinate calculations The coordinate software sets up view coordinates for an image in horizontal screen units of mirror steps (.25 degrees) with the positive direction toward the right and vertical screen units of pixel separation (about .23 degrees depending on the spin rate) with the positive direction toward the top. The origin is at the center of the Earth. Real view coordinates are associated with the image pixel positions, or with integer screen positions within the window if the image is displayed. Since spacecraft motion is noticeable in many auroral images, the orbit data given in the file header record are used to determine spacecraft positions at the time of the nadir crossing for each scan line position in the display window or within the image limits if the image is not displayed. Coordinate systems used include: GEOGRAPHIC (GEO) Z-axis toward north pole, X-axis toward Greenwich meridian, usually expressed as geocentric north latitude and east longitude in degrees, and radial distance in km; GEOCENTRIC EQUITORIAL INERTIAL (GEI) Z-axis toward north pole, X-axis toward the first point of Aries, may be expressed as rectangular coordinates or as right ascension in hours or degrees and declination in degrees; GEOCENTRIC SOLAR EQUITORIAL (GSE, GSEQ, GSEq) Z-axis toward north pole, X-axis toward sun, usually expressed as rectangular coordinates; VIEW (VW) X-axis from spacecraft toward center of Earth, Y-axis is cross product of X-axis and the spin vector, horizontal coordinate (XS) is view latitude in units of scan line width, vertical coordinate (YS) is view longitude in units of pixel height. Using the calculated spacecraft positions and the orbit and attitude data from the file header record, conversions are done between view coordinates and the GSEq system. Other transforms allow conversion between GSEq coordinates and geographic or GEI coordinates. Specific subroutines for converting to and from view coordinates include VW2GEO (view to geographic), VW2GEI (view to GEI), GEO2VW (geographic to view), and GEI2VW (GEI to view). These are described below. Basic image overlays consisting of the limb of the Earth at 0 km. altitude and a terminator at 0 km. altitude and at solar elevation angles of 0 degrees for vacuum-ultraviolet images (photometer 3) and -8 degrees for visible images (photometers 1 and 2) may be drawn over a displayed image using the top-level program MAP. This program uses the subroutines CURRENT_IMAGE and SETCRD to set up the image and window coordinates. The user's input through CURRENT_IMAGE should be identical to the input for displaying the image. Features are drawn from the subroutines LIMB and TERM through WPLOT which uses th user-supplied graphics output subroutines DRAW and MOVE. For associating coordinates with pixels in image files that are not displayed, the top-level program PIXCRD is provided to demonstrate the conversion of scan line mirror position and pixel index to view coordinates by calling PXLOC. The view coordinates are then transformed to geographic coordinates by VW2GEO and to GEI coordinates by VW2GEI. The opposite process is demonstrated by the top-level program CRDPIX. It transforms input geographic or GEI coordinates to view coordinates with GEO2VW or GEI2VW, and then converts view coordinates to scan line mirror position and pixel index by calling LOCPX. Additionally, both PIXCRD and CRDPIX provide luminosities in kilorayleighs for the pixels in question. GRAPHICS_SUBPROGRAMS_REQUIRED: These must be provided by the user and should fit the following specifications. A sample set of graphics routines for software testing is included in the TESTPLOT.FOR file. DSPLIN fills in one vertical line of pixels on the display device with an ------ array of integer values starting from a given position and filling down from that point. name type description input arguments: LINEX INT*2 horizontal screen position for top of line LINEY INT*2 vertical screen position for top of line LINEOUT INT*2 array of values to be displayed ITOTAL INT*2 number of elements in LINEOUT calling sequence: CALL DSPLIN(LINEX,LINEY,LINOUT,ITOTAL) MOVE moves the pen position to a given point on the display. ---- DRAW draws a line from the last pen position to a given point on the display. ---- SETPLT selects and initializes output display device. ------ WRAPUP sends the contents of the plot command buffer to the display device, ------ then releases the device. SOURCE_CODE_FILE_CONTENTS: file name purpose programs and/or subprograms ---------- ------- --------------------------- CRDPIX.FOR coordinates CRDPIX CURRENT_IMAGE.FOR general setup CURRENT_IMAGE DELIB.FOR coordinates CROSS,DCROSS,DNRMLIZ,EQTIME,GEIGSE, GEOGSE,GSEGEI,GSEGEO,NRMLIZ,QUAD, RADIUS,RECSPHD,SPHDREC,SUN,YEAR4 DEVIEW.FOR coordinates COUNTS,DEZA,GEI2VW,GEO2VW,GSESCPOS, GSESC2VW,GSE2VW,LMPLAN,LOCPX,LSDIST, POINT,PXLOC,RADC2VW,SCPOS,SZA,TRUEX, TRUEXS,UTPIX,VWDRGEI,VW2GEI,VW2GEO, VW2GSESC,XPOS DISPLAY.FOR image display BLOCKA,BLOCKD,DISPLAY_IMAGE,EVENOUT, FILLEM1,FILLEM2,LINEARA,LINEARD IMAGEIN.FOR general setup IMAGEIN,ISINK IMDSP.FOR image display IMDSP MAP.FOR plot over LIMB,MAP,TERMIN display PIXCRD.FOR coordinates PIXCRD PLOT.FOR plot over WCOORD,WPLOT display SETCRD.FOR coordinate DEORBIT,MOTION,SECTORS,SETCRD, setup SETIMCOORD,SETWNCOORD,SPINS TESTPLOT.FOR graphics output DRAW,DSPLIN,MOVE,SETPLT,WRAPUP testing MAIN_PROGRAM_DESCRIPTIONS: IMDSP calls DISPLAY_IMAGE to display an image as specified by the user ----- through a call to CURRENT_IMAGE. Link with DISPLAY, CURRENT_IMAGE, IMAGEIN, and user-provided graphics output subroutines or TESTPLOT. The file DSPMAP.XMP describes input and output for sample runs of IMDSP and MAP. MAP draws limb and terminator on the current image. Link with --- CURRENT_IMAGE, SETCRD, DEVIEW, DELIB, PLOT, and user-provided graphics output subroutines or TESTPLOT. The file DSPMAP.XMP describes input and output for sample runs of IMDSP and MAP. PIXCRD uses CURRENT_IMAGE to prompt user for image file identification, sets ------ up the image file for coordinate calculations, then gets geographic and GEI coordinates, universal time, and luminosity for a sampling of pixels from every tenth scan line in the image. Output is to the user's terminal. Link with CURRENT_IMAGE, IMAGEIN, SETCRD, DEVIEW, and DELIB. The file PIXCRD.XMP has sample input and output for three PIXCRD runs. CRDPIX uses CURRENT_IMAGE to prompt user for image file identification, sets ------ up the image file for coordinate calculations, then for input geographic or GEI coordinates, returns pixel location in the file, view coordinates, and luminosity. Link with CURRENT_IMAGE, IMAGEIN, SETCRD, DEVIEW, and DELIB. The file CRDPIX.XMP has sample input and output for a CRDPIX run. COMMON_BLOCK_DESCRIPTIONS: DE SAI software uses the following nine common blocks, described below in this order: 1. MAFREC 2. IMAGE 3. SCANS 4. IWINDOW 5. WINDOW 6. IMCOORD 7. MOTION 8. SCREEN 9. WSCALE 1. MAFREC The MAFREC common block contains the image file's header record in the HEADER array and the first scan line record in the SCAN array. Variables are declared for the individual fields in the records and are equivalenced to the byte arrays. Individual software routines show only the declarations for variables in this block that are immediately needed. The entire list of declarations is given here. All of the field descriptions are given in SAIDOC.SFD in the data file formats. This block is initialized by reading the first two file records into HEADER and SCAN, as is done in IMAGEIN and SETCRD. COMMON /MAFREC/ HEADER,SCAN ! BYTE HEADER(404),SCAN(174) ! INTEGER*2 WORDS,BLOCKFCTR,BYTES,NADCORFLAG,IMSYNCVERS, & XS3CHARS(2),SCOFFSET,XS3NAMES(4) BYTE RESERVED(8),ASCNAME(8) INTEGER*4 FTYPE,YEAR,DAY,MSEC,PHOTID,FWVOLT,FWCODE,FWTEMP, & FIRSTMLC,LASTMLC,LINES,PIXINMAF,MAXPIXINLINE, & DIN(5),GRAYDIN(2),DIGHSKPG(2),MMC,ANLGSUBCM(4), & ORBIT,SCPOS(3),SPINVCTR(3),NORMAL(3),UIPROCTIME, & VEL(3),SUN(3),SPINRATE,OAMSEC,SPINPERIOD, & MINSPIN,MAXSPIN ! EQUIVALENCE (HEADER( 1), WORDS), (HEADER( 97), MMC), & (HEADER( 3), BLOCKFCTR), (HEADER(101),ANLGSUBCM(1)), & (HEADER( 5), BYTES), (HEADER(117), ORBIT), & (HEADER( 9), FTYPE), (HEADER(121), SCPOS(1)), & (HEADER(13), YEAR), (HEADER(133), SPINVCTR(1)), & (HEADER(17), DAY), (HEADER(145), NORMAL(1)), & (HEADER(21), MSEC), (HEADER(157), UIPROCTIME), & (HEADER(25), PHOTID), (HEADER(161), VEL(1)), & (HEADER(29), FWVOLT), (HEADER(173), SUN(1)), & (HEADER(33), FWCODE), (HEADER(185), SPINRATE), & (HEADER(37), FWTEMP), (HEADER(189), OAMSEC), & (HEADER(41), FIRSTMLC), (HEADER(193), SPINPERIOD), & (HEADER(45), LASTMLC), (HEADER(197), MINSPIN), & (HEADER(49), LINES), (HEADER(201), MAXSPIN), & (HEADER(53), PIXINMAF), (HEADER(205), NADCORFLAG), & (HEADER(57),MAXPIXINLINE), (HEADER(373), RESERVED(1)), & (HEADER(61), DIN(1)), (HEADER(381), ASCNAME(1)), & (HEADER(81), GRAYDIN(1)), (HEADER(389), IMSYNCVERS), & (HEADER(89), DIGHSKPG(1)), (HEADER(391), XS3CHARS(1)), & (HEADER(395), SCOFFSET), & (HEADER(397), XS3NAMES(1)) ! INTEGER*4 LMSEC INTEGER*2 LWORDS,LBYTES,DCU,PIXOFFSET,NADCOR(3),ORDERNC BYTE MLC,ANMIRLOC,ANFWPOS,SUBCOMNO,PIXEL(150) ! EQUIVALENCE (SCAN( 1),LWORDS), (SCAN(12), SUBCOMNO), & (SCAN( 3), LBYTES), (SCAN(13), DCU), & (SCAN( 5), LMSEC), (SCAN(15),PIXOFFSET), & (SCAN( 9), MLC), (SCAN(17),NADCOR(1)), & (SCAN(10), ANMIRLOC), (SCAN(23), ORDERNC), & (SCAN(11), ANFWPOS), (SCAN(25), PIXEL(1)) 2. IMAGE The IMAGE common block identifies the image file and specifies how the image is to be centered and expanded if displayed. This block is initialized in CURRENT_IMAGE and is used in both display and coordinate software. COMMON /IMAGE/ IMFILE, !fully qualified file specification & NPHOT, !photometer ID (1, 2, or 3) & CENTRMLC, !mirror location for center of display & PIXOFF, !offset to pixel at top of display & FCTDWN, !vertical expansion factor & FCTACR !horizontal expansion factor ! CHARACTER*128 IMFILE INTEGER*2 NPHOT,CENTRMLC,PIXOFF REAL*4 FCTDWN,FCTACR 3. SCANS The SCANS common block contains pixel values and image alignment data for every scan line in the image. The scan lines are entered into the arrays in time order, the order in which they are read from the image file. If the mirror positions indicate one or more missing scan lines, the pixels and mirror locations for those array entries are set to -1 and the number of pixels is set to 0. This block is initialized by IMAGEIN. It is used by the display software and by the coordinate subroutines that deal with pixel positions in the file and pixel values (PXLOC, LOCPX, COUNTS). COMMON /SCANS/ SCANPIX, !pixels from one scan line in each column & LNCOR, !total correction in pixels for alignment ! of each scan line & MLCS, !mirror location count for each scan line & NPIXL !number of pixels in each scan line ! BYTE SCANPIX(150,121) REAL*4 LNCOR(2,121) INTEGER*2 MLCS(121),NPIXL(121) 4. IWINDOW The IWINDOW common block has the limits of the graphics display window in integer screen coordinates. This block is initialized in CURRENT_IMAGE and is used by display and coordinate software. COMMON /IWINDOW/IXMIN, !left edge X-coordinate & IXMAX, !right edge X-coordinate & IYMIN, !top edge Y-coordinate & IYMAX !bottom edge Y-coordinate ! INTEGER*2 IXMIN,IXMAX,IYMIN,IYMAX 5. WINDOW The WINDOW common block has the limits of the graphics display window in real view coordinates. This block is initialized in SETWNCOORD which is invoked by SETCRD. It is used by the coordinate software. COMMON /WINDOW/ WNXMIN, !left edge view X-coordinate & WNXMAX, !right edge view X-coordinate & WNYMIN, !bottom edge view Y-coordinate & WNYMAX !top edge view Y-coordinate ! REAL*4 WNXMIN,WNXMAX,WNYMIN,WNYMAX 6. IMCOORD The IMCOORD common block contains the image's left, right, and top view coordinates, pixel dimensions, direction of mirror motion and angle to mirror step, spin periods, time tags, and filter altitude and sensitivity. This block is initialized in SETIMCOORD which is invoked by SETCRD. It is used by the coordinate software. COMMON /IMCOORD/IMXMIN, !leftmost scan line view X-coordinate & IMXMAX, !rightmost scan line view X-coordinate & IMYMAX, !top of image view Y-coordinate & STEP, !angle in degrees from nadir to mirror step & MDIREC, !mirror motion, 1=left to right, ! -1=right to left & PIXWD, !pixel width in degrees & PIXHT, !pixel height in degrees & NSPIN, !spin period with respect to nadir in msec & TSPIN, !360 degree spin period in msec & UTNC1, !UT of first scan line nadir crossing in msec & SOLMSEC1, !apparent solar time for first scan line ! nadir crossing in msec & SP, !filter sensitivity factor & ALTF !filter default altitude in km ! REAL*4 IMXMIN,IMXMAX,IMYMAX,STEP,PIXWD,PIXHT,SP,ALTF INTEGER*2 MDIREC INTEGER*4 NSPIN,TSPIN,UTNC1,SOLMSEC1 7. MOTION The MOTION common block contains the variables that give the sun position, spin vector, and the spacecraft position for each scan line position in the display window. It also has the angles between the spacecraft positions and the spin vector. This block is initialized by the subroutine MOTION which is invoked by SETCRD. It is used by the coordinate software. COMMON /MOTION/ POSITION, !GSEq spacecraft position vectors in km & SPINANG, !angles in degrees between spin vector and ! each vector in POSITION & XP1, !view X-coordinate of first row entry ! in POSITION and SPINANG arrays & SPINX, !\ & SPINY, ! >GSEq spin vector (unit vector) & SPINZ, !/ & SUNX, !\ GSEq sun vector (unit vector; Y & SUNZ !/ component is 0.) ! REAL*4 POSITION(1026,3),SPINANG(1026),XP1, & SPINX,SPINY,SPINZ,SUNX,SUNZ 8. SCREEN The SCREEN common block is initialized and used only by DISPLAY_IMAGE and its related subroutines for constructing an output display. COMMON /SCREEN/ EXPANDEDLINES, !scan lines expanded by FCTDWN & XS, !horizontal screen coordinate of & LASTPIX, !number of pixels to be displayed in ! each column in EXPANDEDLINES & LINECOUNT, !current index and total in ! EXPANDEDLINES & ITOTAL, !total vertical length of screen ! display window & MDIREC !direction of mirror motion, ! 1 = left to right, ! -1 = right to left ! REAL*4 EXPANDEDLINES(768,121),XS(121) INTEGER*2 LASTPIX(121),LINECOUNT,ITOTAL,MDIREC 9. WSCALE The WSCALE common block is initialized by WCOORD and used only by WPLOT to scale view coordinates to integer screen coordinates. COMMON /WSCALE/ XSC, !horizontal scale factor & YSC, !vertical scale factor & XOFF, !horizontal offset & YOFF !vertical offset ! REAL*4 XSC,YSC,XOFF,YOFF IMPORTANT_SUBPROGRAM_DESCRIPTIONS_IN_ALPHABETICAL_ORDER: Full descriptions of all subprograms are included with the source code. The following descriptions are for those subprograms that are of primary interest to the user. COUNTS returns compressed and uncompressed pixel count and line-of-sight ------ intensity in kilorayleighs for the input mirror location count and pixel index. It requires a previous call to IMAGEIN. Conversion to kilorayleighs uses preflight values of instrument calibrations. No corrections are provided for inflight radiation degradation. No corrections are made for background and albedo contamination. name type description input arguments: PMLC INT*2 mirror location count of scan line INDEX INT*2 pixel position in scan line output arguments: CCOUNT INT*2 compressed count UCOUNT INT*2 uncompressed count SCLINT REAL*4 spacecraft line-of-sight intensity in kilorayleighs calling sequence: CALL COUNTS(PMLC,INDEX,CCOUNT,UCOUNT,SCLINT) CURRENT_IMAGE gets specifications from user for current image. It may be ------------- modified for input in any convenient mode. If the image is to be displayed, window limits, image position, and expansion factors must be specified; otherwise, defaults are supplied. name type description input argument: DSP LOG*1 .TRUE. if a display window is to be set up input from user for file ident: IMFILE CHAR fully qualified image file name; up to 128 characters in length for image display: IXMIN INT left window edge on display device IXMAX INT right window edge IYMIN INT top window edge IYMAX INT bottom window edge CNTMLC INT mirror location count of image scan line to go in center of window PIXOFF INT numbers of pixels to be skipped in the scan line record before the top of the display FCTDWN REAL image expansion factor calling sequence: CALL CURRENT_IMAGE(DSP) DEZA is a REAL*4 function that returns the spacecraft zenith angle ---- at the point defined by the input view coordinates and altitude. name type description input arguments: XS REAL*4 horizontal view coordinate YS REAL*4 vertical view coordinate ALT REAL*4 altitude in kilometers result: DEZA REAL*4 spacecraft zenith angle in degrees at input point calling sequence: DEZA(XS,YS,ALT) DISPLAY_IMAGE displays any portion of an image to any magnification inside ------------- the specified screen window. Interpolation schemes and magnification factors are specified both for interpolating down a scan line and for interpolating between scan lines. CENTRMLC gives the mirror location to be placed in the center of the window and PIXOFF is the offset to the first pixel at the top of the window. If CENTRMLC is zero, the nominal center scan for that photometer is used as default. Nothing is displayed outside of the window boundaries. Cosmetic improvements are optional depending on the value of the CSMTCS1 and CSMTCS2 flags. name type description input arguments: IMFILE CHAR*128 complete image file name IXMIN INT*2 left screen coordinate of window IXMAX INT*2 right screen coordinate of window IYMIN INT*2 top screen coordinate of window IYMAX INT*2 bottom screen coordinate of window INTDWN INT*2 number giving scheme for expanding down a scan line: 1 = no interpolation, 2 = linear interpolation FCTDWN REAL*4 vertical magnification factor INTACR INT*2 number giving scheme for expanding between scan lines, same options as for INTDWN FCTACR REAL*4 horizontal magnification factor CENTRMLC INT*2 MLC of the display's center scan line PIXOFF INT*2 offset to the display's top pixel CSMTCS1 LOG*1 signals if one or two missing scan lines and fill data are to be interpolated and short lines extended CSMTCS2 LOG*1 signals if counts over 127 to be zeroed calling sequence: CALL DISPLAY_IMAGE(IMFILE,IXMIN,IXMAX,IYMIN,IYMAX, & INTDWN,FCTDWN,INTACR,FCTACR,CENTRMLC,PIXOFF, & CSMTCS1,CSMTCS2) GEIGSE rotates the input GEI vector to GSEq coordinates. ------ name type description input arguments: XGEI REAL*4\ YGEI REAL*4 >GSEq vector components ZGEI REAL*4/ SUNRA REAL*4 right ascension of sun in degrees output arguments: XGSEQ REAL*4\ YGSEQ REAL*4 >GSEq vector components ZGSEQ REAL*4/ calling sequence: CALL GEIGSE(XGEI,YGEI,ZGEI,SUNRA,XGSEQ,YGSEQ,ZGSEQ) GEOGSE converts the input geographic north latitude and east longitude ------ to a GSEq unit vector. name type description input arguments: GLAT REAL*4 geographic north latitude in degrees GLONG REAL*4 geographic east longitude in degrees SOLMSEC INT*4 apparent solar time in milliseconds output arguments: XGSEQ REAL*4\ YGSEQ REAL*4 >GSEq vector components ZGSEQ REAL*4/ calling sequence: CALL GEOGSE(GLAT,GLONG,SOLMSEC,XGSEQ,YGSEQ,ZGSEQ) GSEGEI rotates the input GSEq vector to GEI coordinates. ------ name type description input arguments: XGSEQ REAL*4\ YGSEQ REAL*4 >GSEq vector components ZGSEQ REAL*4/ SUNRA REAL*4 right ascension of sun in degrees output arguments: XGEI REAL*4\ YGEI REAL*4 >GEI vector components ZGEI REAL*4/ calling sequence: CALL GSEGEI(XGSEQ,YGSEQ,ZGSEQ,SUNRA,XGEI,YGEI,ZGEI) GSEGEO rotates the input GSEq vector to geographic north latitude ------ and east longitude. name type description input arguments: XGSEQ REAL*4\ YGSEQ REAL*4 >GSEq vector components ZGSEQ REAL*4/ SOLMSEC INT*4 apparent solar time in milliseconds output arguments: GLAT REAL*4 geographic north latitude in degrees GLONG REAL*4 geographic east longitude in degrees calling sequence: CALL GSEGEO(XGSEQ,YGSEQ,ZGSEQ,SOLMSEC,GLAT,GLONG) GEI2VW converts GEOCENTRIC EQUITORIAL INERTIAL coordinates to view ------ coordinates. It sets VIS to .FALSE. if the point is not visible. name type description input arguments: XGEI REAL*4\ YGEI REAL*4 >GEI position vector in km. ZGEI REAL*4/ output arguments: XS REAL*4 horizontal view coordinate YS REAL*4 vertical view coordinate VIS LOG*1 .TRUE. if input point is visible to spacecraft; .FALSE. if not calling sequence: CALL GEI2VW(XGEI,YGEI,ZGEI,XS,YS,VIS) GEO2VW converts geographic N LAT and E LONG in degrees to view coordinates. ------ VIS is set to .FALSE. in GSE2VW if the point is not visible. name type description input arguments: GLAT REAL*4 geographic north latitude in deg. GLONG REAL*4 geographic east longitude in deg. ALT REAL*4 altitude in kilometers output arguments: XS REAL*4 horizontal view coordinate YS REAL*4 vertical view coordinate VIS LOG*1 .TRUE. if input point is visible to spacecraft; .FALSE. if not calling sequence: CALL GEO2VW(GLAT,GLONG,ALT,XS,YS,VIS) GSE2VW converts GEOCENTRIC SOLAR EQUITORIAL coordinates to view ------ coordinates. It sets VIS to .FALSE. if the point is not visible. name type description input arguments: XGSEQ REAL*4\ YGSEQ REAL*4 >GSEq position vector in km. ZGSEQ REAL*4/ output arguments: XS REAL*4 horizontal view coordinate YS REAL*4 vertical view coordinate VIS LOG*1 .TRUE. if input point is visible to spacecraft; .FALSE. if not calling sequence: CALL GSE2VW(XGSEQ,YGSEQ,ZGSEQ,XS,YS,VIS) IMAGEIN opens the input image file and for each scan line unpacks the ------- pixels and saves the corrections as real pixel units in the SCANS common block. It puts the header record and the first scan line record into the MAFREC common block. name type description input argument: IMFILE CHAR fully qualified image file name, up to 128 characters in length calling sequence: CALL IMAGEIN(IMFILE) LIMB draws the portions of the limb at the input altitude visible ---- in the view window. name type description input argument: ALT REAL*4 altitude in kilometers output: calls to graphics output routines to produce the limb outline calling sequence: CALL LIMB(ALT) LOCPX returns the view coordinates for the input mirror location count ----- and pixel index. name type description input arguments: PMLC INT*2 mirror location count of scan line INDEX INT*2 pixel position in scan line record output arguments: XS REAL*4 horizontal view coordinate YS REAL*4 vertical view coordinate calling sequence: CALL LOCPX(PMLC,INDEX,XS,YS) POINT computes GSEq points of intersection with the Earth spheroid at the ----- altitude ALT for the line of sight indicated by the input view coordinates. It sets NP to the number of points (0, 1, or 2) and it sets (X1,Y1,Z1) to the point closer to the spacecraft. name type description input arguments: XS REAL*4 horizontal view coordinate YS REAL*4 vertical view coordinate ALT REAL*4 altitude in kilometers output arguments: NP INT*2 number of points of intersection - 0, 1, or 2 X1\ REAL*4\ GSEq position of line-of-sight Y1 > REAL*4 > intersect with Earth, if there are Z1/ REAL*4/ any; the nearer point of two X2\ REAL*4\ GSEq position of second line-of-sight Y2 > REAL*4 > intersect with Earth is there is Z2/ REAL*4/ one; the farther point calling sequence: CALL POINT(XS,YS,ALT,NP,X1,Y1,Z1,X2,Y2,Z2) PXLOC returns the mirror location count and the pixel index for the input ----- view coordinates. name type description input arguments: XS REAL*4 horizontal view coordinate YS REAL*4 vertical view coordinate output arguments: PMLC INT*2 mirror location count of scan line INDEX INT*2 pixel position in scan line record calling sequence: CALL PXLOC(XS,YS,PMLC,INDEX) RADC2VW finds the view coordinates of the point in the star background ------- indicated by the input right ascension and declination. It sets VIS to .FALSE. if the point is not visible. name type description input arguments: RA REAL*4 right ascension in degrees DC REAL*4 declination in degrees output arguments: XS REAL*4 horizontal view coordinate YS REAL*4 vertical view coordinate VIS LOG*1 .TRUE. if input point is visible to spacecraft; .FALSE. if not calling sequence: CALL RADC2VW(RA,DC,XS,YS,VIS) SETCRD invokes set-up routines for coordinate calculations for current ------ image and current display window. It supplies defaults needed for coordinates only (no display) if a display window has not been established. calling sequence: CALL SETCRD SZA returns the solar zenith angle at the point defined by the input --- view coordinates and altitude. name type description input arguments: XS REAL*4 horizontal view coordinate YS REAL*4 vertical view coordinate ALT REAL*4 altitude in kilometers result: SZA REAL*4 solar zenith angle in degrees at input point calling sequence: SZA(XS,YS,ALT) TERMIN plots the terminator at the input solar elevation or depression angle ------ and altitude to the extent that it is visible from the spacecraft in the view window. name type description input arguments: SEA REAL*4 solar elevation angle in degrees; a negative value indicates solar depression angle ALT REAL*4 altitude in kilometers output: calls to graphics output routines to produce the terminator outline calling sequence: CALL TERMIN(SEA,ALT) VWDRGEI computes the GEI unit vector from the spacecraft for the direction ------- of the input view coordinates. name type description input arguments: XS REAL*4 horizontal view coordinate YS REAL*4 vertical view coordinate output arguments: XGEI REAL*4\ YGEI REAL*4 >GEI unit vector ZGEI REAL*4/ calling sequence: CALL VWDRGEI(XS,YS,XGEI,YGEI,ZGEI) VW2GEI converts view coordinates XS and YS to geocentric equatorial inertial ------ (GEI) coordinates at the altitude of ALT kilometers above the Earth. It sets GOOD to .FALSE. if the line of sight does not intersect the Earth. name type description input arguments: XS REAL*4 horizontal view coordinate YS REAL*4 vertical view coordinate ALT REAL*4 altitude in kilometers output arguments: XGEI REAL*4\ YGEI REAL*4 >GEI position vector in km. ZGEI REAL*4/ GOOD LOG*1 .TRUE. if line of sight intersects Earth; .FALSE. if it does not calling sequence: CALL VW2GEI(XS,YS,ALT,XGEI,YGEI,ZGEI,GOOD) VW2GEO converts view coordinates XS and YS to geographic north latitude and ------ east longitude in degrees assuming altitude of ALT kilometers above the Earth. It also provides geographic local time. GOOD is set to .FALSE. if the line of sight does not intersect the Earth. name type description input arguments: XS REAL*4 horizontal view coordinate YS REAL*4 vertical view coordinate ALT REAL*4 altitude in kilometers output arguments: GLAT REAL*4 geographic north latitude in deg. GLONG REAL*4 geographic east longitude in deg. GLT REAL*4 geographic local time in degrees GOOD LOG*1 .TRUE. if line of sight intersects Earth; .FALSE. if it does not calling sequence: CALL VW2GEO(XS,YS,ALT,GLAT,GLONG,GLT,GOOD) UTPIX is an integer*4 function that returns the UT in milliseconds ----- for the collection time of the pixel at the input view position. name type description input arguments: XS REAL*4 horizontal view coordinate YS REAL*4 vertical view coordinate result: UTPIX INT*4 pixel collection UT in msec. calling sequence: UTPIX(XS,YS)