GETORB 2.3.2 -- README

This README file pertains to the distribution of getorb_2.3.x.tar.gz. Read this file carefully before installing or using the different components.

Last modification: 25 Nov 2008

Contents

  • Introduction
  • What's new
  • Installation
  • Delft Orbits
  • Listing ODRs with lodr
  • Interpolating orbits with getorb.a and getorb
  • Date conversions with convdate
  • More Information

    • Introduction

    This is the latest release of the software supporting the Delft ERS orbits. The software consists of a program lodr to list the content of the Orbital Data Records (ODRs), a subroutine library getorb.a that can be ported to some other program to interpolate the orbits and any given moment, and an example program getorb to demonstrate the use of the getorb.a library.

    The FORTRAN source code works on nearly all Unix workstations, including Little Endian machines such as DEC workstations (running Ultrix) and PCs (running Linux), as well as Big Endian machines: IBM RS6000, SGI, Convex, Mac, HP.

    What's new ?

    New in Version 2.0 is the use of a new format for the ODRs. Because of the demand from the InSAR community to have a more accurate cross-track resolution, the latitude and longitude coordinates are now in 10^-7 degrees (0.1 microdegree). This also meant changing the interval for the longitudes from 0/360 to -180/+180 degrees. Obviously, the new subroutine handles both the old (1.0 microdegrees) and new resolution data sets.

    A couple of additional enhancements have been made to reduce the number of code lines and to prepare the software for satellites Envisat and Jason.

    Those who have been using former versions of the getorb.a library are recommended to use the new one. It avoids problems when switching to the enhanced resolution data sets in the near future.

    With Version 2.0 all previous versions expired. Version 2.1 and later are Y2K compliant.

    Additional changes after the release of Version 2.1.0 are:

    2.3.2 (25 Nov 2008)
    Extended valid arc-length for the default satellite name from 10 to 400 days. This prevents the warning code when using custom-made very long ODR files.
    2.3.1 (31 May 2006)
    Replaced do-loop with reals in getorb_main.f by "while"-type loop.
    2.3.0 (10 Jan 2006)
    Removed fastio so that source is fully Fortran.
    2.2.0 (22 Nov 2004)
    Allow arc numbers larger than 999.
    2.1.10 (13 Aug 2004)
    Made sure no unwarrented error exits are given with "unknown satellites."
    2.1.9 (5 Aug 2004)
    Removed trap for unknown satellites in odrinfo.f. Additional functionality in mdate.f
    2.1.8 (21 Nov 2003)
    Include of unistd.h added to fastio.c to work on Mac OS X and Cygwin. Update of Makefile (more help).
    2.1.7 (17 Jun 2003)
    New version of fastio.c included, plus related changes. Removed need for sysdep.h in Fortran sources. Included ltlend.f.
    2.1.6 (6 Mar 2003)
    New version of fastio.c included, plus related changes.
    2.1.5 (16 Nov 2000)
    Changes to the Makefile and odrinfo.F for compatibility with newer Linux versions (e.g. Redhat 7.0)
    2.1.4 (27 Oct 2000)
    Update of manual. Small change to convdate.
    2.1.3 (11 Apr 2000)
    Added convdate program. No functional changes to getorb.
    2.1.2 (25 Jan 2000)
    Added source for lnblnk. No functional changes.
    2.1.1 (26 Nov 1999)
    Minor change of SEC85. New manual.
    2.1.0 (9 Nov 1999)
    Made Y2K compliant. Introduced convdate.

    Installation

    There are only a couple considerations for making the programs work properly:

    Once any changes have been made to the makefile, you should be able to compile the library and the two programs via make all or simply make.

    After you make the program, you can make test to check that the outputs agree with reference files included in the tar archive. It runs the programs lodr and getorb and compares the resulting output files with included references.

    Finally, once you've successfully tested the program you can make install to place the executables in /usr/local/bin (or wherever you like if you modify the BIN_DIR parameter in the Makefile); and then make clean to remove the relocatable files.

    To compile the additional utility convdate use make convdate. Since this requires interaction with a C routine, its compilation has been kept separate from the rest.

    Delft Orbits

    Delft ERS-1 orbits are generally available through the anonymous FTP site at NOAA: ftp://falcon.grdl.noaa.gov/pub/delft/ODR.ERS-1. Various subdirectories relate to the different orbit determination versions (different gravity models or tracking data). Recently also ERS-2 orbits are added on the same site: ftp://falcon.grdl.noaa.gov/pub/delft/ODR.ERS-2.

    These directories contain the Orbital Data Records (ODRs) spanning each 5.5-days with a 2-day overlap with consecutive ODRs. The binary format of the ODRs (and some more information) is given in the file docs/odr_fmt.txt. To list the contents of the ODRs use the program lodr.

    For the most up-to-date information of the status of the ERS-1 and ERS-2 orbit determination and details consult the DUT/DEOS Web page with the URL: 

    http://www.deos.tudelft.nl/ers/precorbs/

    Orbit files can also be accessed through this page.

    Store all the ODR files (at least for your required period) in one directory together with the list of ODR files arclist. The name of this directory is one of the input variables for the orbit interpolation routine.

    Listing ODRs with lodr

    The program lodr lists the contents of an ODR. The syntax is: 
           lodr [-s n=n0,n1 t=t0,t1] ODR-filename

    where

    -s
    Print a summary only
    n=n0,n1
    Request listing of record numbers n0 through n1 only
    t=t0,t1
    Requests listing of records of period t0 through t1 only, where t0 and t1 may be specified as MJD.D, [YY]YYMMDD.D, or [YY}YYMMDDHHMMSS.S. To specify epochs as YYDDD.D use the prefix doy= in stead of t=. For Seconds of 1985 use the prefix sec=. After 2003 the use of prefix t= will not properly recognise MJD.D, use prefix mjd= instead.
    ODR-filename
    Name of the input ODR file.

    This program is included in the getorb package and is made with make lodr, but also with make all or just make. When executing the tests (make test) the proper functioning of lodr is checked as well.

    Interpolating orbits with getorb.a and getorb

    The program getorb is a little quick'n'dirty front-end to the getorb library getorb.a. The program allows you to interpolate the DUT orbit at any required epoch (during the span of the data files) or for a range of epochs. The program prints out time (UTC), error value, latitude, longitude, orbital altitude (GRS80), and XYZ (Earth Fixed). The syntax: 
           getorb [t=|ymd=|mjd=|doy=|sec=]t0[,t1,dt] [+]path

    where:

    t0
    epoch for the orbit interpolation in various date formats.
    t0,t1,dt
    start and end epoch (as above) and step size (in seconds) for the orbit interpolation
    ymd=
    indicates that the epochs are specified as [YY]YYMMDD.DDD or [YY]YYMMDDHHMMSS.SSS. You may use the extra century indication, but it is not necessary for any date between 1950 and 2049.
    mjd=
    indicates that the epochs are in Modified Julian Dates (MJD).
    doy=
    is used when epochs are specied as [YY]YYDDD.DDD (year and day of year)
    sec=
    specifies epochs in UTC seconds since 1 January 1985.
    [t=]
    t= is an optional prefix. In will try to identify whether MJD.D, [YY]YYMMDD.D, or [YY]YYMMDDHHMMSS.S where specified (same as when t= is omitted. After 2003 the use of prefix t= will not properly recognise MJD.D, use prefix mjd= instead.
    path
    full or relative path name of the directory in which the ODR files are stored. When a + is added in front of the path name, the path name is considered to be of a single ODR file.

    Examples: 

       getorb mjd=50001.500 /home/ers2/ODR
   getorb ymd=991231235959,000101000159,60 .

    The getorb.a library contains all subroutines used by the getorb program. See the file getorb.F for a detailed information of the use of this routine.

    Date conversions with convdate

    Since the Delft orbits are time tagged in seconds from 1985 and you may like to handle year-month-day, year-dayofyear, or MJD, date conversions are often necessary. You'll see in getorb_main.f how this is done with the subroutines sec85 and mdate. These two routines are also at the heart of a nice little tool what runs from the command line. It accepts almost any from of input date and writes it out in almost any date format you like too. In addition it can add some extra time to the data you give. Very practical to determine the day of tomorrow.

    The syntax: 

           convdate [options]  

Converts specified  into a string according to 

where [options] are:
  offs=delta : add 'delta' seconds to given 
  offm=delta : add 'delta' minutes to given 
  offh=delta : add 'delta' hours to given 
  offd=delta : add 'delta' days to given 

and  is either:
  ymd=[YY]YYMMDD.D       : Year-Month-Day
  ymd=[YY]YYMMDDHHMMSS.S : Year-Month-Day-Hour-Minutes-Seconds
  mjd=MJD.DDD            : Modified Julian Day
  doy=[YY]YYDDD.DDD          : Year-DayOfYear
  sec=SEC85.SSS          : Seconds since 1.0 Jan 1985
  [t=]MJD or [YY]YYMMDD[HHMMSS] : free choise

and  is either:
  +ymd    : YYMMDDHHMMSS.SSS (real)
  +YMD    : same as +%y%m%d%H%M%S (int)
  +mjd    : Modified Julian Day (real)
  +MJD    : Modified Julian Day (int)
  +sec    : Seconds since 1.0 Jan 1985 (real)
  +SEC    : Seconds since 1.0 Jan 1985 (nint)
  +txt    : same as +%c (int, default)
  +doy    : same as +%y%j (int)
  + : Format spec like 'date' command (int)

    More Information

    For more up-to-date information on this package and the DUT orbits, netsurf to http://www.deos.tudelft.nl/ers/precorbs/ or contact: Remko Scharroo (remko@deos.tudelft.nl)

    DEOS This was brought to you by Remko Scharroo, remko@deos.tudelft.nl