# $Id: antenna_cal,v 1.3 2005/10/19 21:38:54 wib Exp $
# Antenna Table Format Description DRAFT
# Any line starting with "#" is a comment

This file format is meant to be read by programs that make namelist
input for qregres and construct namelist items for NMLOPtCenD,
NMLOCen, ... for orbiting spacecraft and NMLGPtCenD, NMLGCen, ... for
ground/station type objects (receivers or transmitters ) by data
type. See /goa/source/qregres.nml for details on the
namelist. Currently this file is read by /goa/bin/gd2p.pl and the
reading is implemented in a perl library
/goa/perl_pm/antenna_cal_reader.  It is constructed in such a way that
multiple files can be concatonated ( cat file1 file2 ... > file ).

For each spacecraft or ground object, data type, and antenna number
( antenna numbers start at 1 ), there must be 1 line before the 
actual calibration table with the following fields separted by white 
space.

Info: Name satellite||ground Ant_no Data_type Az_Incr(deg) Elev_Incr(deg) Elev_start(deg)

where

Name            = name of the receiver or transmitter. 
		  Examples: JASON, GOL2, GPS43, GRACEA
Ant_no          = antenna number; 1 for objects with just one antenna
		  (most applications have Ant_no = 1)
Data_type       = L1,L2,P1,P2,LC,PC 
Az_Incr(deg)    = Increment in azimuth, must be an integer such that 
	 	  360%Az_Incr = 0
                  values in the data line must be included from 0 Az to 360 - Az_incr

Elev_Incr(deg)  = Increment in elevation, must be an integer such that
		  90%Elev_Incr = 0
                  values in the data line must be included from Elev_start to 90.

Elev_start(deg) = Must be an integer multiple of Elev_Incr. Values less than this 
                  elevation will be assumed 0.0.


Note the keyword "Info:". 
Azimuth values start at 0.0 deg. Azimuth is measured in a clockwise sense relative to 
the reference directions. For a fixed antenna on the earth this is usually relative
to North and East would be at 90 deg. azimuth (the antenna bore sight points up ). For 
a satellite antenna the reference direction is a function of how the orientation of the 
antenna is specified in the spacecraft body fixed coordinates.

Elevation values start Elev_start.
Elevation goes to 90 deg.
Azimuth goes to 360 deg. 
No_Az = Number of Azimuth steps = 360/Az_Incr
No_El = Number of Elevation steps = 1 + ((90-Elev_start)/Elev_Incr)

Following this line, for future expansion there could be other
lines with keywords which are currently ignored. A keyword must
start with a capital letter at the beginning of the line, contain no 
white space and end with a ":". After the keyword lines there must 
be No_Az*No_El data lines ( comments lines can be freely interspersed )

Data line format:

Az(deg)   El(deg)   value(mm)   sigma (mm)   Num_obs

Az      - Must be an integer multiple of Az_Incr
El      - Must be an integer multiple of El_Incr
value   - Values for Az/El grid points < Elev_start are assumed to be zero.
sigma   - Uncertainty in value (optional field)
Num_obs - Weighted sum of observations associated with that grid point
	  where the weight is derived from the billinear interpolation
	  of the observation location from the surrounding grid points.

The table of values are used to compute calibrations for the given antenna
phase center and data type. If the phase center is located at vector position 
Vphase the unit vector from Vphase to the other transmitter or receiver (from
Vphase) is Direc, then the correction to Vphase is:

            Vphase = Vphase - Cal*Direc

where Cal is the value obtained by bilinear interpolation of the values in the 
table at an Azimuth and Elevation corresponding to Direc.