lib/libetx.a
Earth transform functions are used to relate TeraScan dataset coordinates (line,sample) to geodetic coordinates (lat,lon). A dataset with an earth location transform has attributes that parameterize the following pair of 2-way transforms:
a. dataset (line,sample) <-> projection (y,x)
b. projection (y,x) <-> geodetic (lat,lon)
The first transform shown above is a simple 2-D affine transform:
a[0] * et y + a[2] * et x + b[0] = line
a[1] * et y + a[3] * et x + b[1] = samp
Projection coordinates correspond to either common map projection coordinates (y,x) in kilometers, or to sensor scan coordinates (line,sample).
Map projection (y,x) <-> (lat,lon) transforms are based on simple mathematical equations. The names and codes of map projections currently supported are listed in the files include/etnames.h and include/etx.h, respectively. The map projections currently supported are:
STEREO_PROJ - Oblique Stereographic (Conformal)
RECT_PROJ - Rectangular (Cylindrical, Fixed Latitude Spacing)
ORTHO_PROJ - Orthographic
POLARSTEREO_PROJ - Polar Stereographic (Conformal)
EQUIDIST_AZIM_PROJ - Equidistant Azimuthal
MERC_PROJ - Mercator (Conformal)
UTM_PROJ - Universal Transverse Mercator
POLYCONIC_PROJ - Polyconic
LAMBERT_AZIM_PROJ - Lambert Azimuthal Equal-Area
LAMBERT_CONIC_PROJ - Lambert Conformal Conic
ALBERS_CONIC_PROJ - Albers Equal-Area Conic
MOLLWEIDE_PROJ - Mollweide
CYLINDRICAL_PROJ - Cylindrical Equal-Area
PERSPECTIVE_PROJ - Generic vertical perspective
EMERC_PROJ - Mercator (Ellipsoid Earth)
GEORECT_PROJ - SeaSpace Georectangular
All projections are based on a spherical earth except for POLARSTEREO_PROJ, EMERC_PROJ, LAMBERT_CONIC and ALBERS_CONIC. These projections are based on a geodetic (elliptic) earth.
For the sphere, the earth's semi-major axis = semi-minor axis = 6378.137 km, with zero eccentricity. For the ellipsoid, the earth's semi-major axis = 6378.137 km, with flattening = 1/298.25722354 (eccentricity = 2*f - f*f). This is commonly referred to as the WGS84 ellipsoid.
For all projections based on a spherical earth, standard parallels coincide with the center latitude of the projection. For the polar stereographic projection, the standard parallel is specified by the proj_param attribute. For the Albers and Lambert conics, the proj_param attribute specifies the distance in degrees from the center latitude to the standard parallels. For example, if the center lat is 35n, and proj_param=5, then the standard parallels are 30n and 40n.
These projections are described in the publication entitled Map Projections used by the U.S. Geological Survey, Bulletin 1532 by John P. Snyder. georect is a SeaSpace-invented projection for displaying geostationary sa tellite data in a non-cylindrical rectangular format.
The sensor scan transform (line,sample) <-> (lat,lon) is evaluated by flying the satellite forward and backward over the earth, and looking through the eye of the sensor. The names and codes of the sensors currently supported are listed in the files include/etnames.h and include/etx.h respectively. The satellites and sensors currently supported are:
| SATELLITES | SENSORS |
| noaa | avhrr, hirs |
| dmsp | ols, ssmi, ssmt1, ssmt2 |
| goes | vissr (vas) |
| gms | svissr |
| meteosat | mvissr |
| nimbus | czcs |
Sensor-based earth transforms are computed using satellite ephemeris and sensor geometry information obtained from the following files:
$SATDATA/satellite/sensor
A given dataset can have both a map projection-based and a sensor-based earth transform. In such cases, the affine transform relates dataset (line,sample) to map projection (y,x). Dataset (line,sample) can be related to sensor scan (line,sample) by the following strategy:
dataset (line,sample) <-> map projection (y,x) map projection (y,x) <-> geodetic (lat,lon) geodetic (lat,lon) <-> sensor scan (line,sample)
Parameters defining an earth transform are stored in TeraScan datasets using the following global attributes:
| attribute | type | len | units |
| projection | long | 1 | std_projection |
| center_lat | double | 1 | std_latitude |
| center_lon | double | 1 | std_longitude |
| satellite | string | 11 +1 | |
| sensor | long | 1 | std_sensor |
| pass_date | long | 1 | std_date |
| start_time | double | 1 | std_time |
| attitude | double | 3 | radians |
| time_adjust | double | 1 | std_time |
| sensor_tilt | double | 1 | radians |
| sensorient | double | 5 | radians |
| scan_samples | long | 1 | |
| et_affine | double | 6 | |
| scan_rates | double | 3 | radians/sec |
| map_angle | double | 1 | radians |
| proj_param | double | 1 | std_latitude |
| scan_time | double | 1 | std_time |
| use_orbele | long | 1 | |
| miss_algn_mat | double | 9 | |
| center_line | double | 1 | |
| center_sample | double | 1 | |
| step_line | double | 1 | radians |
| step_samp | double | 1 | radians |
| gc_radius | double | 1 | radians |
| gc_width | double | 1 | radians |
| interp_points | long | 1 | |
| int_times | double | interp_points seconds | |
| x_coord | double | interp_points meters | |
| y_coord | double | interp_points meters | |
| z_coord | double | interp_points meters | |
| x_head | double | interp_points | |
| y_head | double | interp_points | |
| z_head | double | interp_points | |
| sensor_tilt_arr | double | interp_points radians | |
| sensor_twist | double | interp_points radians | |
| satellite_roll | double | interp_points radians | |
| satellite_pitch | double | interp_points radians | |
| satellite_yaw | double | interp_points radians | |
| nutat_matrix | double | interp_points *9 |
These attribute names and units are defined in include/etx.h. Only projection, center_lat, center_lon, et_affine, and map_angle are needed if the transform is based on a map projection. proj_param is currently only used for POLARSTEREO_PROJ; it denotes the projection parallel latitude.
Sensor and projections are stored in coded form. Routines are provided for converting to and from name form. The projection for a sensor-based earth transform is SENSOR_PROJ.
Long ago, TeraScan earth transforms were applicable only to dataset variables with dimensions explicitly named line and sample. Now, earth transforms can apply to all variables with X and Y coordinate dimensions! Dataset dimensions have a built-in attribute coord that can take on any of the following values: GP_X_COORD, GP_Y_COORD, GP_Z_COORD, GP_TIME_COORD, GP_NO_COORD. These values are defined in include/gp.h.
Built-in dimension attributes scale and offset relate variable coordinates to dataset (Y,X) or (line,sample) coordinates. Dimension scale and offset typically change as a result of subsetting and subsampling operations. For example, dimension D, starting with D=P with a step size of Q, to create a new dimension D', then
D'->coord = D->coord D'->scale = P * D->scale D'->offset = Q * D->scale + D->offset
Earth transform interface functions fall into one of the following categories:
| Edit Parameters | |
| Evaluate Transform | Store Transform |
| Satellite State | Utility Functions |
| Inquire Parameters |
Setup functions enable an earth transform based on user-supplied parameters or parameters retrieved from an open TeraScan dataset. These functions include:
gpetready set up earth transform using parameters stored in a dataset
gpetvready set up earth transform for a particular dataset variable
projready set up map projection based earth transform
orbready set up sensor-based earth transform
Evaluation functions apply previously enabled earth transforms. These functions include:
etxll compute (lat,lon) from file (line,sample)
lletx compute file (line,sample) from (lat,lon)
projll compute (lat,lon) from map projection (y,x)
llproj compute map projection (y,x) from (lat,lon)
sensorll compute (lat,lon) from sensor (line,sample)
llsensor compute sensor (line,sample) from (lat,lon)
etcoords compute projection (y,x) from file (line,sample)
State functions return satellite information for the last sensor-based earth transform computation. These functions include:
ettime return date and time
etdata3 return satellite orbital information
Inquire functions return current values of earth transform parameters. These functions include:
etadjtim get absolute satellite clock adjustment
etsetatt get satellite attitude angles
etgettilt get sensor tilt angle
etgetmap get affine transform coefficients
etgetproj get projection
Edit functions change the values of earth transform parameters. These functions include:
etadjtim set absolute satellite clock adjustment
etsetatt set satellite attitude angles
etsettilt set sensor tilt angle
etsetmap set affine transform coefficients
etremap compose current affine transform with another affine transform
etsubsect change affine transform to match file (line,sample) subsampling
etgcpmap change affine transform to match list of ground control points
Store functions write earth transform parameters to a TeraScan dataset. There is only one such function:
etstore store transform parameters in TeraScan dataset
Utility functions are those functions that do not fall into any of the above categories. These functions include:
projcode get code for a given projection name
projname get name for a given projection code
sensorcode get code for a given sensor name
sensorname get name for a given sensor code
lldist compute distance between 2 (lat,lon) points
llxyz compute geocentric (x,y,z) for (lat,lon)
xyzll compute (lat,lon) for geocentric (x,y,z)
sunxyz compute unit sun vector (x,y,z) for given date and time
sunazm compute sun azimuth and elevation for given date, time, and (lat, lon)
etllbox compute approximate (lat,lon) 'square' covering a file (line,sample) subsection
llazimuh Return azimuth from (lat,lon) to (x,y,z) measured clockwise from North (e.g., east => 90, west => 270)
llheading Return heading from (lat,lon) to (lat2,lon2). Lat, lon, and heading are all in degrees. Heading is measured like azimuth
sidereal Return sidereal time in radians for given (date, time).
All the parameters for an earth transform are encoded in a single data structure called an 'earth transform array'. Earth transform arrays are initialized by setup functions, and modified by evaluation and editing functions. An earth transform array is declared in a C program as:
ETXFORM name1, name2, ...;
The ETXFORM datatype is defined in include/etx.h.
A program can declare several earth transform arrays. However, due to the current implementation of the earth transform subsystem, a program can have at most one active sensor-based earth transform at a time.
Earth transform functions return -1 on error with error status stored in the global variable terrno. Most error codes are found in include/etx.h. Codes for dataset errors encountered while trying to store an earth transform are listed in include/cdf.h.
ET_OPEN_SENSOR Unable to open sensor file
ET_OPEN_SENSOR Unable to read sensor file
ET_READ_ELEMS Unable to open orbital elements file
ET_READ_ELEMS Unable to read orbital elements file
ET_UNKOWN_PROJ Unknown projection passed or encountered
ET_SINGULAR Earth transform affine mapping is singular
ET_BAD_PARAMETER Bad parameter passed to setup routine
ET_NO_CONVERGENCE Satellite/sensor calculation failed to converge
ET_DF_CONES Sensor look angles are bogus
ET_OUTER_SPACE Sensor is pointing into outer space
ET_UNKOWN_SENSOR Unknown sensor code or name.
ET_ORB_PATH Cannot find directory containing satellite data
ET_NO_TRANSFORMS Missing earth transform attributes
include/gp.h, include/etx.h, include/etnames.h, lib/libetx.a, lib/libcdf.a, lib/libutils.a, $SATDATA/satellite/orbdata, $SATDATA/satellite/sensor
etcoords, etmisc, etnames, etnav, etready, etxll, datasets
WARNING - Due to its Fortran heritage, all (line,sample) coordinates input to or output from this subsystem are assumed to be 1-relative. This includes both file and sensor scan coordinates.
Before the polar stereographic, Lambert conic, and Albers conic projections were intorduced to TeraScan, a given map projection was parameterized simply by its center latitude and longitude, pixel height and width at the center, and an angle of rotation. All parameters except the center lat/lon were boiled down to the 6-element et_affine attribute.
When the polar stereographic projection was introduced, we added a new dataset attribute proj_param to store the standard parallel. Then when the Lambert and Albers conic projections were introduced, the same proj_param attribute was used to imply the standard parallels.
Last Update: $Date: 2001/05/17 23:17:41 $