# Initial definition Willy Bertiger 7/8/99

This file contains descriptions of two possible pos_goa file formats, and a binary record format
used in shared memory (sometimes directly converted into packets for network transport):
    (1) ASCII  - suggested suffix .pos[.gz]
    (2) Binary - suggested suffix .posb[.gz]
    (3) Binary record
Both file formats (1) and (2) may be gzip compressed.

GENERAL REMARKS
---------------
This describes the pos_goa file format, containing position components as a time series.
Files and records may also contain: velocity components, the sigmas of each 
component and attitude information (quaternions). Quaternions are an extension 
of the format originating in Gipsy-OASIS (GOA).

It was initially designed for the SRTM project, but has since found other uses.

*All* lines must be strictly time ordered (earliest times first); this is a 
departure from the GOA format which only required that all lines with the same
name (field 1) be time ordered.

IMPORTANT NOTE: in this document, we refer to an epoch we call J2000GPS.
* J2000GPS is distinct from the epoch J2000.0, which the IAU 1994 Resolution 
  C7 recommends be defined at the geocenter and at the date 2000 January 1.5 
  Terrestrial Time(TT), where TT = TDT. 
* J2000GPS is also distinct from the date 2000 January 1.5 UTC time, which we
  can refer to as J2000UTC. Exactly 13 leap seconds separate these epochs, i.e.: 
      J2000GPS = J2000UTC - 13 = 2000-01-01 11:59:47.000 UTC
* Times before and after J2000GPS are described in GPS seconds around this epoch, 
  i.e. continuous time.
  
Time past J2000GPS is represented using an integer (t_i) and a double (t_f) value: 
t = t_i + t_f. This time representation can have femto-second accuracy for 68 years 
from J2000GPS (2**31/86400/365 ~= 68.09, i.e. good for 68 years to 1 second from 
J2000GPS). If you do not need this precision, you could of course set t_i = 0 and 
write t_f as double seconds past J2000GPS, as it currently is in many software sets.

Negative sigmas are typically used to indicate the invalidity / unreliability 
of the corresponding coordinate fields. A sigma of -1 indicates that the
corresponding values are dummy values. For example, if velocity is unavailable 
yet there are 20 fields, there will be dummy velocity values in fields 7-9 
and sigmas of -1 in fields 13-15. A sigma of -2 indicates that the 
corresponding value may be unreliable. For files containing predictions of the 
GPS orbits, sigmas of -2 may occur to indicate the existence of a NANU that 
might affect prediction accuracy. A sigma of -3 indicates that the sigma value
itself is a dummy value, just there to provide padding so that you can add
quaternion values in fields 16-19 even if you don't actually have sigma values.

If q0 + q1i + q2j + q3k is any quaternion (Q), then q0 is called its scalar
part and q1i + q2j + q3k is called its vector part. This quaternion should
transform a vector in the satellite body-fixed coordinate system (Vbfs) to a 
vector in the coordinate system identified in field 0 (Vs):

    Vs = R.Vbfs

R is a rotation matrix derived from Q - see Quaternion::toRotationMatrix()

(1) ASCII file
This file contains an arbitrary number of lines with white space delimited 
fields. 

Any line starting with a "#" is ignored and considered a comment.
# E.g. This is a comment line.

Comments may also occur at the end of lines, from the first occurrence of a "#"
character onwards.

Blank lines are ignored.
  
EXAMPLE (in practice, this should all be on one line)
-------
E GPS23 403261200 0.000000000000000E+00 
 6.908861669097966E+03 2.586420363513870E+04  2.024301610397836E+03 
-2.151127514999478E-01 2.818405550198080E-01 -3.107165379202010E+00 
 1.987857905662623E-05 1.497527077719072E-05  2.616444941599272E-05 
 1.902071840949898E-09 3.041361607611697E-09  1.390785228979385E-09 
 4.213090921042242E-02 1.449777480113355E-01  7.188055942732944E-01 -6.786198911851030E-01

FIELD NUMBERS AND DESCRIPTIONS
------------------------------
Fields 0-6 are REQUIRED, while fields >=7 are OPTIONAL.

0   E or I for Earth-Fixed or Inertial respectively. Note that nothing 
    inherently limits this to a single character in order to allow for more  
    descriptive or exact coordinate systems.
1   Name of object (satellite, station, ??? ); white-space is not allowed in 
    the name. The name must start with an alphabetic character, but can then 
    contain any alphabetic character [a-z,A-Z], non-negative integer [0-9], or 
    an underscore. For GOA version 4, names must be less than 6 characters, there
    is no limitation in GCORE/gipsyX to the length of names. 
2   Integer (t_i) seconds past J2000GPS. To get GPS seconds past GPS week 0 
    second 0, ( 6-JAN-1980 00:00:00.0000), add 630763200; we assume this is a 
    signed int in c, and integer*4 in Fortran.  
3   Float seconds (t_f) past t_i, double for c, REAL*8 for Fortran.
4   X position component (km)   
5   Y position component (km)   
6   Z position component (km)   
7   X velocity component (km/s) 
8   Y velocity component (km/s) 
9   Z velocity component (km/s)
10  X position sigma (km) 
11  Y position sigma (km)
12  Z position sigma (km)
13  X velocity sigma (km/s)
14  Y velocity sigma (km/s)
15  Z velocity sigma (km/s)
16  Unit attitude quaternion, scalar component
17  Unit attitude quaternion vector, i component
18  Unit attitude quaternion vector, j component
19  Unit attitude quaternion vector, k component

The total number of possible fields is 20.
 
All 3 components ( XYZ ) must appear if any one component appears, e.g.:

    E DUMMY 5 0.3 10 20 30 0.02

is NOT VALID, but: 

    E DUMMY 5 0.3 10 20 30 0.02 0.03 0.01

is valid. Likewise, all components of the quaternion must be specified if a
value appears in field 16.

See $GOA/bin/jpl2pos_goa, $GOA/bin/rsmsig.pl, $GOA/bin/readoi, 
and $GOA/bin/podiff.

(2) Binary file
Binary pos_goa files contain one protocol/handshake record at the top of each 
file and then, each data record *must* contain certain entries but *may* also 
contain optional fields:
    
    ---------------------------- Mandatory -------------------------------------
    
    *** Protocol record - once at the top of each file
    
      char        'p' - record ID for file protocol
      13          a hex coded string that evaluates to "JPLRTGXPOSGOA"
      
    *** Record - once per object per epoch

      char        'r' - record ID for pos_goa record values  
      uint8_t     file format version number 
      char        descriptor for optional fields. 8 bit flags, all zero by default:
                      bit 0 - set only if velocities are being written
                      bit 1 - set only is XYZ position sigmas are being written
                      bit 2 - set only if XYZ velocity sigmas are being written
                      bit 3 - set only if a quaternion is being written
                      bits 4-7 - spare
      uint64_t    "length" of the coordinate system name string
      length      coordinate system name string
      uint64_t    "length" of the object name string
      length      object name string
      int64_t     integer part of the epoch's TimePrecise representation (seconds past J2000GPS)
      double      double part of the epoch's TimePrecise representation (seconds past J2000GPS)
      3 x double  X, Y, Z position components (km)

    ---------------------------- Optional --------------------------------------
          
      3 x double  X, Y, Z velocity components (km/s) iff descriptor bit 0 is set 
      3 x double  X, Y, Z position sigmas (km) iff descriptor bit 1 is set 
      3 x double  X, Y, Z velocity sigmas (km/s) iff descriptor bit 2 is set
      4 x double  scalar, (i, j, k) unit attitude quaternion components iff  
                  descriptor bit 3 is set


(3) Binary record

Binary pos_goa records take the following form, with all variables in native Linux (little-endian) formatting.

8 bytes: uint64_t = total record size = 137 + <sat_name_size> [+ 32 if quaternions present] for typical records
8 bytes: uint64_t = <coord_sys_name_size> = size of coordinate system name, typically = 1
<coord_sys_name_size> bytes: coordinate system name string, typically = "E" (Earth-fixed)
8 bytes: uint64_t = <sat_name_size> = size of <sat_name> string
<sat_name_size> bytes: actual <sat_name> string
8 bytes: int64_t = integer part of ttag (J2000GPS seconds)
8 bytes: double = fractional part of ttag (seconds)
3*8 bytes: 3*double = position components (km)
3*8 bytes: 3*double = velocity components (km/s)
3*8 bytes: 3*double = position sigma components (km)
3*8 bytes: 3*double = velocity sigma components (km/s)

[optional 4*8 bytes: 4*double = quaternion components ]

See PosGOA for a C++ reader/interpolator.