GCLgrid :: GCLgrid classes

class GCLgrid

? ^ 
    extends BasicGCLgrid as public

This is the working two-dimensional version of a GCLgrid.

A GCLgrid defines a two-dimensional surface in Earth coordinates. This could be any surface, but the lookup method used in this version will not work if the surface is multivalued or even strongly warped. See the algorithm description in the paper by Fan and Pavlis (in review) for details.

Positions of grid points are stored in three, two-dimensional arrays. Each of these arrays define cartesian coordinates for a grid point at a particular index position. The topology is that the location in the Cartesian coordinate system of the grid point defined by index positions i and j are (x1[i][j], x2[i][j], x3[i][j]). The coordinates are thus matrices indexing each position in grid.

Note the object inherits most data attributes from the BasicGCLgrid object.

Source:
gclgrid.h:296
Author:
unascribed
Version:
unknown
Friends:
class GCLscalarfield undocumented
class GCLvectorfield undocumented

Contents

^ 
EntityInherited FromTypeScopeShort Description
~GCLgriddestructor public Destructor.
GCLgridconstructor public Default constructor.
GCLgridconstructor public Simple constructor.
GCLgridconstructor public Constructor for what we call a "regular" GCLgrid in the Fan and Pavlis (in review) paper.
GCLgridconstructor public Antelope database driven constructor.
GCLgridconstructor public Standard copy constructor.
compute_extentsmethod publicundocumented
ctogBasicGCLgridmethod public Convert Cartesian coordinates to geographical coordinates.
ctogBasicGCLgridmethod public Convert from Cartesian coordinates to geographical coordinates.
dbsavemethod public Save grid to an Antelope (Datascope) database.
depthmethod public Get the depth below the standard reference ellipsoid of a grid point.
fetch_transformation_matrixBasicGCLgridmethod public Returns the transformation matrix for this grid as a 3x3 dmatrix object.
fetch_translation_vectorBasicGCLgridmethod public Returns a newly allocated 3 vector of double containing a copy of the translation vector defining the GCLgrid transformation property.
geo_coordinatesmethod public Returns the geographical coordinates of a point in the grid specified by grid index positions.
get_indexmethod publicSee BasicGCLgrid::get_index
gtocBasicGCLgridmethod public Convert from geographical to Cartesian coordinates in the GCLgrid coordinate system.
gtocBasicGCLgridmethod public Convert from geographical to Cartesian coordinates in the GCLgrid coordinate system.
latmethod public Get the latitude (in radians) of a grid point.
lonmethod public Get the longitude (in radians) of a grid point.
lookupmethod public Find the index position of a point in a GCLgrid.
operator =operator public Standard assignment operator.
rmethod public Get the radius from the center of the Earth of a grid point.
reset_indexmethod publicSee BasicGCLgrid::reset_index
set_transformation_matrixBasicGCLgridmethod public Set or reset the transformation properties for the grid.
x1attribute public n1 x n2 matrix of the x1 coordinate values for grid elements.
x2attribute public n1 x n2 matrix of the x2 coordinate values for grid elements.
x3attribute public n1 x n2 matrix of the x3 coordinate values for grid elements.

destructor ~GCLgrid

? ^  > 
Destructor.

Nontrivial destructor has to destroy the coordinate arrays correctly and handle case when they are never defined. Handles this by checking for NULL pointers for these arrays. If the pointers are NULL the free routines are not called. This is important to know if you try to create a GCLgrid object by the default constructor.

Source:
gclgrid.h:375
Code:
public ~ GCLgrid ( )

constructor GCLgrid

? ^  < > 
Default constructor.

Note it sets the x1,x2, and x3 pointers to NULL which is used as a test to avoid duplicate free calls on these potentially large arrays.

Source:
gclgrid.h:320
Code:
public GCLgrid ( )

constructor GCLgrid

? ^  < > 
Simple constructor.

Allocates space for x1, x2, and x3 arrays and initializes other data attributes to zero.

Source:
gclgrid.h:328
Params:
n1 number of grid points on generalized coordinate axis 1.
n2 number of grid points on generalized coordinate axis 2.
Code:
public GCLgrid ( int n1size ,
int n2size )

constructor GCLgrid

? ^  < > 
Constructor for what we call a "regular" GCLgrid in the Fan and Pavlis (in review) paper.

The object this constructs is a constant geoid elevation surface (Follows the reference ellipsoid at elevation set by the origin radius, r0.) with approximately regular spacing between grid points (within the limits of what is possible on a spherical surface). Note that the makegclgrid program is little more than a wrapper around this and the 3d version of this constructor.

Source:
gclgrid.h:353
Params:
n1 number of grid points on generalized coordinate axis 1.
n2 number of grid points on generalized coordinate axis 2.
n name to assign this grid.
la0 latitude to use for origin.
lo0 longitude to use for origin.
radius0 Earth radius to use for origin. If 0 or negative will use r0_ellipse at la0.
az azimuth of great circle path through the origin that defines the generalized coordinate 2 axis direction.
dx1n nominal spacing of grid points on the generalized coordinate 1 axis.
dx2n nominal spacing of grid points on the generalized coordinate 2 axis.
iorigin 1 axis grid index of the origin in generalized coordinate grid frame.
jorigin 2 axis grid index of the origin in generalized coordinate grid frame.

Code:
public GCLgrid ( int n1size ,
int n2size ,
string n ,
double la0 ,
double lo0 ,
double radius0 ,
double az ,
double dx1n ,
double dx2n ,
int iorigin ,
int jorigin )

constructor GCLgrid

? ^  < > 
Antelope database driven constructor.

This is a specialized constructor that loads a grid tagged with the name nm from a database using a specialized table. Users who do not wish to connect with Antelope should remove this constructor from the object definition.

Source:
gclgrid.h:363
Params:
db Antelope database pointer.
nm name of grid to be loaded from the database.
Code:
public GCLgrid ( Dbptr db ,
string nm )

constructor GCLgrid

? ^  < > 
Standard copy constructor.
Source:
gclgrid.h:367
Code:
public GCLgrid ( const GCLgrid & )

method compute_extents

? ^  < > 
undocumented
Source:
gclgrid.h:469
Code:
public void compute_extents ( )

method ctog

? ^  < > 
Convert Cartesian coordinates to geographical coordinates.
Inherited From:
BasicGCLgrid
Source:
gclgrid.h:208
Params:
x1p - Cartesian x1 coordinate of point to convert
x2p - Cartesian x2 coordinate of point to convert
x3p - Cartesian x3 coordinate of point to convert
Returns:
Geographic_point data structure (see Geographic_point )
Code:
public Geographic_point ctog ( double x1p ,
double x2p ,
double x3p )

method ctog

? ^  < > 
Convert from Cartesian coordinates to geographical coordinates.
Inherited From:
BasicGCLgrid
Source:
gclgrid.h:214
Param:
p point to convert stored in a Cartesian_point data structure
Returns:
Geographic_point data structure (see Geographic_point )
Code:
public Geographic_point ctog ( Cartesian_point p )

method dbsave

? ^  < > 
Save grid to an Antelope (Datascope) database.

This routine writes the object attributes to a special table and writes the grid coordinate data an output file. Note the file name used to store the grid is the same as the name parameter passed to this function.

Source:
gclgrid.h:397
Params:
db Antelope database pointer.
nm name used to save the grid.
Exception:
int Exception is thrown if save failed. A simple int exception is used because errors are posted to the Antelope elog mechanism. If this exception is caught, call elog_complain to flush the elog buffer.

Code:
public void dbsave ( Dbptr db ,
string nm ) throw ( int )

method depth

? ^  < > 
Get the depth below the standard reference ellipsoid of a grid point.

Source:
gclgrid.h:467
Params:
i1 Value of grid index 1 for point desired.
i2 Value of grid index 2 for point desired.
Returns:
depth in kilometers of the requested grid point.
Code:
public double depth ( int i1 ,
int i2 )

method fetch_transformation_matrix

? ^  < > 
Returns the transformation matrix for this grid as a 3x3 dmatrix object.
Inherited From:
BasicGCLgrid
Source:
gclgrid.h:194
Code:
public dmatrix fetch_transformation_matrix ( )

method fetch_translation_vector

? ^  < > 
Returns a newly allocated 3 vector of double containing a copy of the translation vector defining the GCLgrid transformation property.

The user must be sure to call delete [] after using this vector to avoid a memory leak.

Inherited From:
BasicGCLgrid
Source:
gclgrid.h:200
Code:
public double * fetch_translation_vector ( )

method geo_coordinates

? ^  < > 
Returns the geographical coordinates of a point in the grid specified by grid index positions.

If you need the actual coordinates of the points that define the grid converted to geographic coordinates use this function. Use the ctog function to convert an arbitrary ordered triplet.

Source:
gclgrid.h:435
Params:
i1 Value of grid index 1 for point desired.
i2 Value of grid index 2 for point desired.
Returns:
grid point requested in an Geographic_point data structure.
Code:
public Geographic_point geo_coordinates ( int i1 ,
int i2 )

method get_index

? ^  < > 
See BasicGCLgrid::get_index
Source:
gclgrid.h:423
Code:
public void get_index ( int * ind )

method gtoc

? ^  < > 
Convert from geographical to Cartesian coordinates in the GCLgrid coordinate system.

Inherited From:
BasicGCLgrid
Source:
gclgrid.h:224
Params:
plat Latitude (radians) of point to convert.
plon Longitude (radians) of point to convert.
pr Earth radius (km) of point to convert.
Returns:
Cartesian_point data structure (see @endlink)reca
Code:
public Cartesian_point gtoc ( double plat ,
double plon ,
double pr )

method gtoc

? ^  < > 
Convert from geographical to Cartesian coordinates in the GCLgrid coordinate system.

Inherited From:
BasicGCLgrid
Source:
gclgrid.h:232
Param:
p point to convert stored in a @link Geographic_point @endlink data structure.
Returns:
Cartesian_point data structure (see @endlink)le
Code:
public Cartesian_point gtoc ( Geographic_point p )

method lat

? ^  < > 
Get the latitude (in radians) of a grid point.

Source:
gclgrid.h:443
Params:
i1 Value of grid index 1 for point desired.
i2 Value of grid index 2 for point desired.
Returns:
latitude in radians of the requested grid point.
Code:
public double lat ( int i1 ,
int i2 )

method lon

? ^  < > 
Get the longitude (in radians) of a grid point.

Source:
gclgrid.h:451
Params:
i1 Value of grid index 1 for point desired.
i2 Value of grid index 2 for point desired.
Returns:
longitude in radians of the requested grid point.
Code:
public double lon ( int i1 ,
int i2 )

method lookup

? ^  < > 
Find the index position of a point in a GCLgrid.

This is a low level function to find the location of a point specified as the Cartesian, ordered pair (x1p,x2p) in a grid. It does not return the actual index positions, but only sets the internal index. The routine is very procedural returning an integer code (see below) indicating success or failure of the lookup. This was intentional as this routine is called millions of times in some contexts so efficiency is critical. The alternative would be to throw an exception when a lookup failed, but since this is viewed as a common problem that could happen millions of times this was a potential efficiency problems (the books all say throwing exceptions is an expensive operation).

Source:
gclgrid.h:419
Params:
x1p - Cartesian x1 coordinate of point to find within the grid
x2p - Cartesian x2 coordinate of point to find within the grid
Returns:
2 when point is in gray area within on nominal grid spacing of the edge 1 when the point is outside the bounding box. 0 on success.\ -1 if the lookup function did not converge.

Code:
public int lookup ( double x1p ,
double x2p )

operator =

? ^  < > 
Standard assignment operator.
Source:
gclgrid.h:379
Code:
public GCLgrid & operator = ( const GCLgrid & )

method r

? ^  < > 
Get the radius from the center of the Earth of a grid point.

Source:
gclgrid.h:459
Params:
i1 Value of grid index 1 for point desired.
i2 Value of grid index 2 for point desired.
Returns:
Earth radius in kilometers of the requested grid point.
Code:
public double r ( int i1 ,
int i2 )

method reset_index

? ^  < > 
See BasicGCLgrid::reset_index
Source:
gclgrid.h:421
Code:
public void reset_index ( )

method set_transformation_matrix

? ^  < > 
Set or reset the transformation properties for the grid.

The transformation properties are uniquely defined by the coordinate system origin and azimuth_y so if these are all that are known this low level member function can be called to set the transformation properties. It is of minimal use to most users and should be used cautiously and only if you thoroughly understand the way this all works.

Inherited From:
BasicGCLgrid
Source:
gclgrid.h:190
Code:
public void set_transformation_matrix ( )

attribute x1

? ^  < > 
n1 x n2 matrix of the x1 coordinate values for grid elements.

Source:
gclgrid.h:302
Code:
public double * * x1

attribute x2

? ^  < > 
n1 x n2 matrix of the x2 coordinate values for grid elements.

Source:
gclgrid.h:307
Code:
public double * * x2

attribute x3

? ^  < > 
n1 x n2 matrix of the x3 coordinate values for grid elements.

Source:
gclgrid.h:312
Code:
public double * * x3

Created Wed Apr 27 07:05:01 2005.
This documentation was generated automatically by
ccdoc v08r41 2004/09/29 bin_opt_suncc_sun4-solaris-2.8.
Click here to submit a bug report or feature request for ccdoc.
Click here to return to the top of the page.